user role tertentu
filter tertentu
network lambat
mutation gagal lalu retry
tab lama masih terbuka
permission berubah di tengah session
query cache stale
component remount tanpa sadar
modal ditutup saat request masih pending

Apa yang user lakukan?
State transition apa yang terjadi?
Command apa yang dikirim?
Query cache mana yang dibaca?
Mutation mana yang gagal?
Route dan search params apa yang aktif?
Workflow sedang di state apa?
Render mana yang mahal?
Apakah state yang diamati aman dari PII?

click button        -> belum tentu penting
submit approval    -> penting
query refetched    -> mungkin penting
query invalidated  -> penting bila memengaruhi user-visible data
modal opened       -> penting bila modal bagian dari workflow
state rerender     -> penting bila mahal atau abnormal
permission denied  -> penting untuk audit UX dan debugging

Do not log everything.
Log the state machine, not the entire heap.
Log transition metadata, not sensitive payload.
Log identifiers and correlation, not full user data.
Log enough to reconstruct the path, not to clone the user's screen.

Domain event:
  CaseApproved
  InvoiceRejected
  UserAssigned

Frontend telemetry event:
  approval_button.clicked
  approval_modal.confirmed
  approval_mutation.failed
  approval_ui.permission_denied

export type TelemetryLevel = 'debug' | 'info' | 'warn' | 'error'

export type TelemetryEvent = {
  name: string
  level: TelemetryLevel
  timestamp: string
  correlationId: string
  route?: string
  screen?: string
  workflowId?: string
  actorId?: string
  queryKeyHash?: string
  mutationId?: string
  userRole?: string
  tenantId?: string
  attributes?: Record<string, string | number | boolean | null>
}

<domain_or_area>.<object_or_flow>.<event>

case.search.submitted
case.search.query_failed
case.search.results_rendered
case.approval.confirm_opened
case.approval.command_started
case.approval.command_failed
case.approval.optimistic_rollback
permission.case_approve.denied
modal.close_requested
workflow.transitioned

button_clicked
clicked
state changed
error happened
search page thing
submit2

function ApproveButton({ caseId, onApprove }: Props) {
  const telemetry = useTelemetry()

  return (
    <button
      onClick={() => {
        telemetry.info('case.approval.intent', {
          caseId,
          source: 'toolbar',
        })
        onApprove(caseId)
      }}
    >
      Approve
    </button>
  )
}

Button tidak tahu click artinya approve.
ApprovalToolbar tahu click artinya approval intent.

type TransitionLog<S, E> = {
  from: S
  event: E
  to: S
  allowed: boolean
}

function instrumentedReducer<S, E>(
  reducer: (state: S, event: E) => S,
  log: (entry: TransitionLog<S, E>) => void,
) {
  return (state: S, event: E) => {
    const next = reducer(state, event)

    log({
      from: state,
      event,
      to: next,
      allowed: next !== state,
    })

    return next
  }
}

log({
  from: state.status,
  event: event.type,
  to: next.status,
  allowed: next !== state,
})

Query key apa yang aktif?
Apakah data fresh atau stale?
Mutation apa yang menginvalidasi query ini?
Apakah user melihat data lama saat refetch?
Apakah error berasal dari network, auth, validation, atau server?

export function useCaseSearch(params: CaseSearchParams) {
  const telemetry = useTelemetry()

  return useQuery({
    queryKey: caseSearchKeys.list(params),
    queryFn: async ({ signal }) => {
      const started = performance.now()

      try {
        const result = await api.searchCases(params, { signal })

        telemetry.info('case.search.query_succeeded', {
          durationMs: Math.round(performance.now() - started),
          status: params.status ?? 'all',
          page: params.page,
        })

        return result
      } catch (error) {
        telemetry.error('case.search.query_failed', {
          durationMs: Math.round(performance.now() - started),
          errorClass: classifyError(error),
        })
        throw error
      }
    },
  })
}

Log query metadata.
Jangan log hasil query penuh.

const approveCase = useMutation({
  mutationFn: api.approveCase,
  onMutate: async (input) => {
    const mutationId = crypto.randomUUID()

    telemetry.info('case.approval.command_started', {
      mutationId,
      caseId: input.caseId,
      optimistic: true,
    })

    return { mutationId }
  },
  onError: (error, input, context) => {
    telemetry.warn('case.approval.command_failed', {
      mutationId: context?.mutationId ?? 'unknown',
      caseId: input.caseId,
      errorClass: classifyError(error),
    })
  },
  onSuccess: (_data, input, context) => {
    telemetry.info('case.approval.command_succeeded', {
      mutationId: context?.mutationId ?? 'unknown',
      caseId: input.caseId,
    })
  },
})

command started
optimistic applied
server success
server failure
rollback/compensation
invalidation performed
navigation/result shown

telemetry.info('workflow.transitioned', {
  workflow: 'caseApproval',
  workflowId,
  from: 'confirming',
  event: 'CONFIRM',
  to: 'submitting',
})

approval flow id: approval-abc
  modal opened
  validation passed
  command started
  optimistic update applied
  server failed
  rollback applied
  error banner shown

import { Profiler } from 'react'

function onRender(
  id: string,
  phase: 'mount' | 'update' | 'nested-update',
  actualDuration: number,
  baseDuration: number,
) {
  if (actualDuration > 16) {
    telemetry.warn('react.render.slow', {
      id,
      phase,
      actualDuration: Math.round(actualDuration),
      baseDuration: Math.round(baseDuration),
    })
  }
}

export function SearchPageProfiled() {
  return (
    <Profiler id="CaseSearchPage" onRender={onRender}>
      <CaseSearchPage />
    </Profiler>
  )
}

raw form values
full server response
full external store snapshot
access token / refresh token
authorization header
PII / sensitive identifiers
password / secret / OTP
large arrays of rows
keystroke-by-keystroke without sampling
render event for every small component

telemetry.info('form.changed', formState)
telemetry.info('query.result', data)
telemetry.info('redux.state', store.getState())

telemetry.info('form.changed', {
  dirtyFieldCount,
  hasValidationErrors,
})

telemetry.info('query.result_received', {
  rowCount: data.items.length,
  total: data.total,
})

telemetry.info('store.transitioned', {
  slice: 'caseSelection',
  from: previous.status,
  to: next.status,
})

export type TelemetryClient = {
  debug(name: string, attributes?: TelemetryAttributes): void
  info(name: string, attributes?: TelemetryAttributes): void
  warn(name: string, attributes?: TelemetryAttributes): void
  error(name: string, attributes?: TelemetryAttributes): void
  span?<T>(name: string, fn: () => Promise<T>): Promise<T>
}

const TelemetryContext = createContext<TelemetryClient | null>(null)

export function TelemetryProvider({
  client,
  children,
}: {
  client: TelemetryClient
  children: React.ReactNode
}) {
  return (
    <TelemetryContext.Provider value={client}>
      {children}
    </TelemetryContext.Provider>
  )
}

export function useTelemetry() {
  const client = useContext(TelemetryContext)
  if (!client) {
    throw new Error('useTelemetry must be used inside TelemetryProvider')
  }
  return client
}

component tidak tahu vendor observability
test bisa mengganti telemetry client
privacy filter bisa dipusatkan
sampling bisa dipusatkan
schema event bisa divalidasi

const SENSITIVE_KEYS = [
  'password',
  'token',
  'authorization',
  'email',
  'phone',
  'address',
  'nationalId',
]

function sanitizeAttributes(input: TelemetryAttributes = {}) {
  const output: TelemetryAttributes = {}

  for (const [key, value] of Object.entries(input)) {
    if (SENSITIVE_KEYS.some((sensitive) => key.toLowerCase().includes(sensitive))) {
      output[key] = '[redacted]'
    } else if (typeof value === 'string' && value.length > 256) {
      output[key] = value.slice(0, 256) + '…'
    } else {
      output[key] = value
    }
  }

  return output
}

schema allowlist per event
PII classification
field-level redaction
sampling policy
retention policy
environment-specific filtering
security review

function useInstrumentedReducer<S, E extends { type: string }>(
  name: string,
  reducer: React.Reducer<S, E>,
  initialState: S,
  selectStateTag: (state: S) => string,
) {
  const telemetry = useTelemetry()

  return useReducer((state: S, event: E) => {
    const next = reducer(state, event)

    if (next !== state) {
      telemetry.info(`${name}.transitioned`, {
        from: selectStateTag(state),
        event: event.type,
        to: selectStateTag(next),
      })
    }

    return next
  }, initialState)
}

Reducer tetap pure.
Instrumentation wrapper berada di boundary React hook.
Log metadata, bukan seluruh state.

function useTransitionObserver<S>(
  name: string,
  state: S,
  selectTag: (state: S) => string,
) {
  const telemetry = useTelemetry()
  const previousRef = useRef<string | null>(null)
  const current = selectTag(state)

  useEffect(() => {
    const previous = previousRef.current
    if (previous !== null && previous !== current) {
      telemetry.info(`${name}.state_changed`, {
        from: previous,
        to: current,
      })
    }
    previousRef.current = current
  }, [current, name, telemetry])
}

type Store<State> = {
  getState(): State
  setState(updater: (state: State) => State, meta?: { event?: string }): void
  subscribe(listener: () => void): () => void
}

function withTelemetry<State>(
  store: Store<State>,
  telemetry: TelemetryClient,
  selectTag: (state: State) => string,
): Store<State> {
  return {
    ...store,
    setState(updater, meta) {
      const previous = store.getState()
      store.setState(updater, meta)
      const next = store.getState()

      telemetry.info('external_store.updated', {
        event: meta?.event ?? 'unknown',
        from: selectTag(previous),
        to: selectTag(next),
      })
    },
  }
}

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      retry: 2,
    },
  },
})

queryClient.getQueryCache().subscribe((event) => {
  // vendor/library event shape bisa berubah; bungkus di adapter internal
  telemetry.debug('query_cache.event', {
    type: event.type,
  })
})

query failed
mutation failed
invalidated important query family
slow query
high retry count
unexpected stale data shown

telemetry.info('case.search.params_changed', {
  status: params.status ?? 'all',
  hasKeyword: params.q.trim().length > 0,
  page: params.page,
  sort: params.sort,
})

hasKeyword: true
keywordLength: 12
keywordTokenCount: 2

telemetry.info('permission.case_approve.evaluated', {
  allowed: decision.allowed,
  reason: decision.reason,
  role: currentRole,
})

allowed: false
reasonClass: missing_capability | resource_locked | state_not_allowed | unknown

User melihat tombol disabled dan bertanya kenapa.
Support perlu tahu reason class.
Engineer perlu tahu apakah UI decision selaras dengan backend denial.
Security perlu memastikan frontend denial bukan satu-satunya enforcement.

class AppErrorBoundary extends React.Component<
  { children: React.ReactNode; telemetry: TelemetryClient },
  { hasError: boolean }
> {
  state = { hasError: false }

  static getDerivedStateFromError() {
    return { hasError: true }
  }

  componentDidCatch(error: Error, info: React.ErrorInfo) {
    this.props.telemetry.error('react.error_boundary.caught', {
      message: error.message,
      componentStack: info.componentStack.slice(0, 1000),
    })
  }

  render() {
    if (this.state.hasError) return <CrashFallback />
    return this.props.children
  }
}

componentStack bisa mengandung nama component internal
error.message bisa mengandung payload bila error dibangun sembarangan
sanitize tetap diperlukan

route.changed /cases
case.search.params_changed status=open page=1
case.search.query_succeeded rowCount=25
case.approval.intent caseId=case-123
case.approval.command_started mutationId=m-1
case.approval.command_failed errorClass=conflict
toast.shown type=error

ringkas
aman dari PII
punya timestamp
punya correlation ID
punya route/screen context

caseId sebagai metric label
userId sebagai metric label
full URL sebagai metric label
search keyword sebagai metric label

screen
workflow
operation
statusClass
errorClass
roleClass

sampling
trace context propagation
CORS/header policy
privacy
vendor cost
browser support
noise level

Low-level primitive <Button> biasanya tidak tahu makna event.
Page/use-case boundary tahu makna event.
Store/machine tahu transition.
Query hook tahu resource operation.

case.approval.confirm_opened
workflow.transitioned from=idle to=confirming event=OPEN_CONFIRM
case.approval.confirmed
workflow.transitioned from=confirming to=submitting event=CONFIRM
case.approval.command_started mutationId=m1
case.approval.command_failed mutationId=m1 errorClass=conflict
workflow.transitioned from=submitting to=failed event=SERVER_ERROR
case.approval.retry_clicked
workflow.transitioned from=failed to=submitting event=RETRY
case.approval.command_succeeded mutationId=m2
workflow.transitioned from=submitting to=succeeded event=SERVER_OK

apakah user benar-benar confirm
berapa kali retry
apakah error conflict atau network
apakah rollback terjadi
apakah UI stuck di submitting

search.params_changed
search.submitted
search.query_started
search.query_succeeded
search.query_failed
search.page_changed
search.sort_changed
search.filter_reset
search.results_rendered
search.empty_state_shown
search.stale_data_shown
search.export_started

{
  status: params.status ?? 'all',
  page: params.page,
  sort: params.sort,
  hasKeyword: params.q.length > 0,
  keywordLength: params.q.length,
  activeFilterCount: countActiveFilters(params),
  resultCount: data.items.length,
  totalBucket: bucketTotal(data.total),
}

full keyword if sensitive
full row data
full response
user personal identifiers

export const consoleTelemetry: TelemetryClient = {
  debug(name, attrs) {
    console.debug(`[telemetry] ${name}`, attrs)
  },
  info(name, attrs) {
    console.info(`[telemetry] ${name}`, attrs)
  },
  warn(name, attrs) {
    console.warn(`[telemetry] ${name}`, attrs)
  },
  error(name, attrs) {
    console.error(`[telemetry] ${name}`, attrs)
  },
}

export function createProductionTelemetry(config: TelemetryConfig): TelemetryClient {
  return {
    debug(name, attrs) {
      if (config.debugSamplingEnabled) send(name, 'debug', sanitizeAttributes(attrs))
    },
    info(name, attrs) {
      send(name, 'info', sanitizeAttributes(attrs))
    },
    warn(name, attrs) {
      send(name, 'warn', sanitizeAttributes(attrs))
    },
    error(name, attrs) {
      send(name, 'error', sanitizeAttributes(attrs))
    },
  }
}

export function createMemoryTelemetry() {
  const events: Array<{ name: string; level: string; attrs?: TelemetryAttributes }> = []

  const client: TelemetryClient = {
    debug: (name, attrs) => events.push({ name, level: 'debug', attrs }),
    info: (name, attrs) => events.push({ name, level: 'info', attrs }),
    warn: (name, attrs) => events.push({ name, level: 'warn', attrs }),
    error: (name, attrs) => events.push({ name, level: 'error', attrs }),
  }

  return { client, events }
}

it('logs approval failure with safe metadata', async () => {
  const { client, events } = createMemoryTelemetry()

  render(
    <TelemetryProvider client={client}>
      <ApprovalFlow caseId="case-123" />
    </TelemetryProvider>,
  )

  await user.click(screen.getByRole('button', { name: /approve/i }))
  await user.click(screen.getByRole('button', { name: /confirm/i }))

  expect(events).toContainEqual(
    expect.objectContaining({
      name: 'case.approval.command_failed',
      level: 'warn',
      attrs: expect.objectContaining({
        caseId: 'case-123',
        errorClass: 'conflict',
      }),
    }),
  )
})

critical mutation failure logged
permission denial logged
workflow stuck prevention logged
PII redaction applied
error boundary emits crash event

development logs bisa terlihat double
jangan anggap duplicate dev event selalu production bug
subscription cleanup harus benar
telemetry effect harus idempotent bila mungkin

log user intent di event handler
log lifecycle effect dengan dedupe bila diperlukan
jangan memakai effect telemetry untuk event business yang harus persis sekali

event schema allowlist
field redaction
PII review
no token/header logging
no full form payload
no full response payload
role-based access to logs
retention policy
sampling policy
user consent/regional policy bila relevan

Kalau data tidak diperlukan untuk menjawab pertanyaan operasional, jangan log.

Apakah approval command gagal karena conflict?
Apakah query search lambat untuk filter status=open?
Apakah user ditolak karena missing capability?
Apakah workflow stuck di submitting?

Apa isi lengkap komentar user?
Apa seluruh data case yang muncul di table?
Apa search keyword mentah user?

Search page query latency by status/filter count
Approval workflow failure rate by error class
Top React render bottlenecks by screen
Permission denied UX events by capability
Mutation rollback count by operation
Workflow stuck count by flow/state
Error boundary crashes by route/component stack hash

Total click events
Total render events
Every context update count
Raw event stream without grouping

[ ] Event punya nama stabil?
[ ] Event menjawab pertanyaan operasional nyata?
[ ] Field-nya aman dari PII/secrets?
[ ] Ada correlation ID yang tepat?
[ ] Cardinality-nya terkendali?
[ ] Event tidak dikirim dari render path?
[ ] Event tidak terlalu sering tanpa sampling?
[ ] Ada test untuk event critical?
[ ] Ada owner untuk schema event?
[ ] Ada retention/access policy?

[ ] start event
[ ] transition events
[ ] command started
[ ] command succeeded/failed
[ ] rollback/compensation
[ ] user-visible result shown
[ ] stuck/timeout signal

Search → Open Detail → Edit → Save → Invalidate Search → Show Toast

1. Event taxonomy
2. Event envelope
3. Correlation IDs
4. Query/mutation telemetry
5. Error boundary telemetry
6. PII redaction policy
7. Test adapter
8. Dashboard metrics

Ketika user bilang data setelah save tidak berubah,
apakah mutation sukses,
query apa yang diinvalidate,
cache mana yang masih stale,
route/search params apa yang aktif,
dan UI state mana yang menampilkan data lama?

Observability frontend adalah desain, bukan console.log.
Instrumentasi terbaik berada di event, command, transition, query, mutation, route, dan workflow boundary.
Jangan dump full state; log metadata aman dan correlation ID.
Frontend telemetry harus punya privacy guardrail.
React Profiler berguna untuk render cost, tapi jangan dicampur dengan business telemetry.
Server-state observability harus mengikuti query key, mutation lifecycle, invalidation, dan stale data.
Workflow observability harus mengikuti state transition.
Observability yang baik membuat bug produksi bisa direkonstruksi tanpa menyalin data sensitif user.