/using-tracing

name: ring:using-tracing
description: "Using lib-observability/tracing for OTEL provider lifecycle, trace-context propagation across HTTP/gRPC/queues, span error/event recording, and PII redaction, in two modes. Sweep Mode detects raw OTEL setup, hand-rolled header propagation, manual span-attribute assembly, and DIY redaction. Reference Mode catalogs Telemetry, Redactor, and propagation/span helpers. Go-only. Skip for non-Go or frontend code."

ring:using-tracing

When to use

Sweep mode:

• "Sweep / audit tracing setup"
• "Find raw OpenTelemetry usage we should replace"
• "Are our HTTP/gRPC boundaries propagating trace context?"
• "Is there DIY field redaction in spans?"
• "Migrate this service to lib-observability/tracing"

Reference mode:

• "How do I bootstrap Telemetry for a new service?"
• "Which Inject/Extract helper do I use for X transport?"
• "How does the Redactor pipeline work?"
• "How do I record a business-error event on a span?"
• "What does RedactingAttrBagSpanProcessor do?"

Skip when

• Working on non-Go services
• Working on frontend code
• Target codebase does not depend on `github.com/LerianStudio/lib-observability`

Related

**Parent:** ring:using-lib-observability **Similar:** ring:using-runtime, ring:using-assert, ring:using-lib-commons

The `tracing` subpackage owns OTEL provider lifecycle, trace context propagation, span helpers, and the attribute-redaction pipeline (`RedactingAttrBagSpanProcessor` is wired automatically inside `NewTelemetry`). Use this skill when tracing is the primary concern. For broader lib-observability sweeps (logging, metrics, panic recovery), invoke `ring:using-lib-observability`.

Mode Selection

| Request Shape | Mode | |---|---| | "Sweep / audit tracing / find raw OTEL / find untraced boundaries" | **Sweep** | | "How do I bootstrap Telemetry?" | **Reference** | | "Inject/Extract helper for HTTP/gRPC/queue?" | **Reference** | | "How does Redactor / span processor work?" | **Reference** |

---

SWEEP MODE

5-phase sweep. Each phase has a hard gate — do not proceed until the current phase produces its artifact.

Phase 1: Version Reconnaissance   → tracing-version-report.json
Phase 2: CHANGELOG Delta Analysis → tracing-delta-report.json
Phase 3: Multi-Angle DIY Sweep    → 6 × tracing-sweep-{N}-{angle}.json
Phase 4: Consolidated Report      → tracing-sweep-report.md + tracing-sweep-tasks.json
Phase 5: Handoff                  → offer ring:running-dev-cycle dispatch

Phase 1: Version Reconnaissance

1. Read `go.mod` — extract pinned version of `github.com/LerianStudio/lib-observability` 2. WebFetch `https://api.github.com/repos/LerianStudio/lib-observability/releases/latest` — extract `tag_name` 3. Classify drift: up-to-date / minor-drift / moderate-drift / major-upgrade / not-imported 4. Emit `/tmp/tracing-version-report.json`: `{pinned_version, latest_version, drift_classification, module_path}`

Phase 2: CHANGELOG Delta Analysis

1. WebFetch `https://raw.githubusercontent.com/LerianStudio/lib-observability/main/CHANGELOG.md` 2. Filter entries affecting `tracing/` (otel.go, obfuscation.go, processor.go) 3. Emit `/tmp/tracing-delta-report.json` with classified entries (`new-api` / `breaking-change` / `security-fix` / `bugfix`)

Phase 3: Multi-Angle DIY Sweep

⛔ STOP-CHECK BEFORE DISPATCH

Before emitting any Task call, count the explorers you intend to launch in this turn.

• Count MUST equal 6.
• If count < 6 → STOP. Do not partial-dispatch. Reconcile against the 6 angles below and try again.
• The 6 angles are the canonical sweep. No substitutions, no omissions.

⛔ MUST NOT trickle-dispatch

All 6 explorers leave in the SAME TURN, before reading any explorer output.

Forbidden sequences:

• Dispatch explorer 1 → read result → dispatch explorer 2
• Dispatch a subset → wait → dispatch the rest
• Dispatch follow-up explorers conditioned on partial output
• Loop sequentially over the angle list

If you find yourself about to dispatch an explorer in a turn AFTER any explorer has already returned a result → STOP. You violated parallel dispatch. Report the violation and mark the phase INCOMPLETE rather than completing the trickle.

Self-verify after dispatch

After the dispatch turn, verify all 6 Task calls were emitted in that single turn. If fewer than 6 went out, the phase did NOT execute correctly. Mark INCOMPLETE and surface the dispatch failure — do NOT silently continue with a partial pool.

Parallel dispatch — atomic batch

Emit all 6 Task calls in a SINGLE TURN, as one atomic batch.

**If your runtime exposes a `multi_tool_use.parallel` wrapper**, use it to dispatch the complete pool in one wrapped invocation. This is the canonical fan-out mechanism on OpenAI-style tool envelopes and on certain Anthropic SDK consumers — naming it explicitly activates parallel emission on runtimes where trickle-dispatch is the default behavior.

**If your runtime emits parallel tool_use blocks natively** (Claude Code with Claude models), `multi_tool_use.parallel` may not be needed — but naming it is harmless and serves as an enforcement anchor.

The STOP-CHECK, anti-trickle, and self-verify guards above remain binding regardless of which mechanism your runtime uses.

Dispatch all 6 explorer angles in **one parallel batch**. Wait for all before Phase 4.

**Per-explorer dispatch** (`subagent_type: ring:codebase-explorer`):

## Target: <absolute path to target repo root>
## Your Angle: <angle number + name from below>
## Severity / DIY Patterns / Replacement / Migration Complexity
<verbatim from angle table below>

## Output
Write to: /tmp/tracing-sweep-{N}-{angle-slug}.json
Schema: { angle_number, angle_name, severity, migration_complexity,
  findings: [{file, line, diy_pattern, replacement, evidence_snippet, notes}],
  summary }
If no findings: write file with empty findings array.

The 6 Angles

| # | Angle | Severity | DIY Pattern | Replacement | |---|---|---|---|---| | 1 | Raw OTEL TracerP