Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

3.5 KB
Raw Blame

description: "Changes to a flow carry the instrumentation to debug it: one correlated trace across services, spans at boundaries, timing, and searchable IDs." alwaysApply: true

Observability

Every new or changed flow must be debuggable from its trace alone: one trace from the user's action through every service it touches, with the timing and IDs needed to answer "what happened to this request and where did the time go". Reviewers treat missing instrumentation on a new flow as a defect, like a missing test. New flows and hot paths are instrumented in the same change, frontend and backend. The routed document load flow (view.* → doc.load) and agent editing (edit.session) are the reference examples; the instrumentation skill walks through them and the per-runtime APIs.

Correlate across hops

  • Propagate W3C trace context on every hop. Inbound HTTP adopts traceparent through macro_tower_layers; outbound Rust HTTP calls inject_trace_headers; Kafka publishes carry trace headers via kafka_util; agent and ACP messages use genai_telemetry::propagation. A new transport (queue message, websocket frame, worker call) needs inject on send and extract on receive. If a hop can't carry context, record the upstream trace id as a span field.
  • Web and Cloudflare Workers use the @macro-inc/observability Telemetry facade (Telemetry.span); don't import OpenTelemetry directly and don't add a second telemetry path (ast-grep ts/tsx-observability-facade).
  • Browser context does not survive an await: retain the parent span (or a Telemetry.captureContext() taken at synchronous admission, before auth or scheduling yields) across awaits and retries, and pass it explicitly, e.g. in mutation variables, never in the request payload. Don't restore global async patches.
  • Web view loading and in-view interactions use @app/observability/flow (TraceFlow, usePending, useFlow().task, beginInteraction), never a hand-rolled root span per load.

Spans at boundaries

  • Span the places a trace would otherwise go dark: queue and Kafka consumers, cross-service client calls, background jobs, and multi-step business operations. Don't span trivial helpers; HTTP handlers already get spans from macro_tower_layers.
  • Name spans for the operation (calendar.sync_account), not the function.
  • Record the IDs you will search by (entity, user, team, session, document) and sizes/counts as fields. Skip bulky or sensitive arguments; never record prompts, message content, tokens, secrets, or personal data (email, username, IP); use opaque ids.
  • Async work that outlives the request (spawned tasks, queued jobs) links to or parents on the span that started it, so the flow stays one trace.

Timing

  • Separate the phases a reader would ask about: queueing vs. execution, network vs. processing, each external call. Long operations get child spans per phase, not one opaque span.
  • Record outcome on the span (error status, retry count, cache hit/miss), so slow and failed paths can be filtered without logs.

Logs

  • Logs are events inside spans with structured fields, not a parallel narrative: one warn! with fields beats several formatted debug!s. Rust specifics are CS-22 in rust/code.md; GenAI spans follow CS-55.

Check: run the changed flow locally and find its trace in Tempo (see the live-debug skill): it is one connected trace across services, phases show their durations, and the span is findable by the entity ID.