otel-tracing
OpenTelemetry tracing discipline: correct spans, propagation, and semantic conventions produce useful traces. Invoke whenever task involves any interaction with distributed tracing — span creation, context propagation, instrumentation, sampling configuration, or OpenTelemetry SDK setup.
xobotyi · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add xobotyi/cc-foundry --skill otel-tracing技能说明
name: otel-tracing description: >- OpenTelemetry tracing discipline: correct spans, propagation, and semantic conventions produce useful traces. Invoke whenever task involves any interaction with distributed tracing — span creation, context propagation, instrumentation, sampling configuration, or OpenTelemetry SDK setup.
OTel Tracing
Create spans for logical operations, propagate context across every boundary, use semantic conventions for attribute names. Every tracing decision — span granularity, attribute selection, sampling strategy — trades off cost against visibility.
References
- Spans — [
${CLAUDE_SKILL_DIR}/references/spans.md]: Span anatomy, root spans, lifetime code patterns - Span data — [
${CLAUDE_SKILL_DIR}/references/span-data.md]: Events format, links format, SDK limits table - Context propagation — [
${CLAUDE_SKILL_DIR}/references/context-propagation.md]: W3C header format, propagator selection, baggage details, security - Instrumentation — [
${CLAUDE_SKILL_DIR}/references/instrumentation.md]: Server/client/async code patterns, library rules, testing guidance - Sampling — [
${CLAUDE_SKILL_DIR}/references/sampling.md]: Head/tail/combined strategies, decision guide, sampler types - Semantic conventions — [
${CLAUDE_SKILL_DIR}/references/semantic-conventions.md]: HTTP/DB/messaging attribute lists, status mapping, general conventions - SDK components — [
${CLAUDE_SKILL_DIR}/references/sdk-components.md]: Resource config, env vars, Collector deployment, exporter types
Spans
A span represents one unit of work in a trace — an HTTP request handler, a database query, a message publish. Not every function call.
Span Naming
Name spans for the class of operation, not the instance. Low-cardinality names enable aggregation; high-cardinality names destroy it.
- Use the most general string that identifies a statistically interesting class
- Never embed high-cardinality values (IDs, emails, paths with IDs)
- HTTP:
{METHOD} {route}— server:GET /users/:id; client:GET - DB:
{operation} {table}—SELECT users,INSERT orders
| Name | Verdict |
|---|---|
get | Too general |
get_account/42 | Too specific — ID in name |
get_account | Good |
GET /users/{userId} | Good — route template |
POST /api/v2/orders/abc123 | Bad — order ID in name |
SpanKind
SpanKind tells backends how to assemble the trace tree. Set it correctly.
SERVER(Incoming) — HTTP handler, gRPC server methodCLIENT(Outgoing) — HTTP client call, DB query, gRPC callPRODUCER(Outgoing) — Enqueue message, schedule jobCONSUMER(Incoming) — Dequeue message, process jobINTERNAL(Neither) — In-process business logic, computation- A single span MUST NOT serve more than one purpose
- Create a new span before injecting context for outgoing calls
CLIENT->SERVERfor synchronous calls;PRODUCER->CONSUMERfor async- Using
INTERNALfor HTTP handlers or DB calls is wrong — useSERVERorCLIENT
Span Status
Unset— No error. Default — do not change on success.Error— Operation failed. When an error occurs; include description.Ok— Explicitly successful. Only to override a previousError; rarely needed.- Leave status
Unseton success — it already means "no error" Okis a "final call" — once set, subsequentErrorattempts are ignored- Instrumentation libraries SHOULD NOT set
Ok— leave to application code
Span Lifetime
- Every created span MUST be ended — leaked spans cause memory issues and incomplete traces
- After
end(), the span becomes non-recording; further mutations are ignored - Use language-idiomatic patterns:
defer(Go), try/finally (Java/JS), context manager (Python)
Span Data: Attributes, Events, Links
Attributes
Key-value pairs annotating a span. Value types: string, boolean, integer, float, or arrays of these.
- Use semantic conventions for attribute names —
http.request.method,db.system, not custom names. Consistent naming enables cross-service analysis. - Add sampling-relevant attributes at span creation — samplers can only see attributes present at creation time.
- Keep cardinality low — attribute values should be from a bounded set.
- Check
IsRecordingbefore expensive attribute computation — sampled-out spans discard all data. - Never store PII in attributes — trace data flows to shared backends. Use opaque identifiers.
- Respect attribute limits — SDK enforces
AttributeCountLimit(default 128). Excess attributes are silently dropped.
Events
Timestamped annotations — structured log entries attached to a span.
- Use events when the timestamp matters; use attributes for metadata with no meaningful timestamp
- Add events for key domain occurrences ("page became interactive", "retry attempted")
- Use events for verbose data instead of additional spans
Recording Exceptions
- Always pair
RecordExceptionwithsetStatus(ERROR)— RecordException alone does not change span status - Never swallow application exceptions in instrumentation — catch instrumentation errors, log them, but always rethrow application exceptions
Links
Associate a span with spans from other traces without parent-child hierarchy.
- Batch processing: link consumer span to each producer span
- Async follow-up: job span links back to triggering span
- Add links at span creation when possible — samplers can consider them
See ${CLAUDE_SKILL_DIR}/references/span-data.md for events format, links format, and SDK limits table.
Context Propagation
Context propagation correlates spans across service boundaries. Without it, each service produces isolated spans — no trace.