Which OpenTelemetry semantic conventions apply to us, and which do not

Triage, filed so the question is answered once rather than re-litigated each time someone reads the conventions index. Workstream of #522; the mechanism for our own domain conventions is #537.

The conventions catalogue is large and most of it is for other kinds of system. Adopting a convention whose meaning does not match our domain is worse than inventing nothing, because it teaches an operator's tooling something false.

Already ours, for free

RPC and Connect RPC. connectrpc.com/otelconnect v0.9.0 is a direct dependency and is wired in production, at cmd/flow/main.go:720, cmd/flow/serverdev.go:724 and cmd/flow/client.go:143, with Temporal's own tracing interceptor alongside it in cmd/flow/telemetry.go. So the RPC conventions arrive without us writing them, which is also why #523 found every internal hop propagating correctly and only the external edges broken.

Action: none, beyond confirming during #523's work that we do not fight the library by hand-rolling attributes it already sets.

Worth adopting

CLI spans (https://opentelemetry.io/docs/specs/semconv/cli/cli-spans/). flow is a CLI, and a substantial amount of real use is flow run local, flow test, flow validate on a developer's machine or in someone's CI. A conventional span for a command invocation, with the command name and exit status, makes those observable with tooling an operator already has, and it is the natural parent for the spans a local run produces. Small, and it fits a surface we already own.

Runtime metrics (https://opentelemetry.io/docs/specs/semconv/runtime/). Verified absent: nothing in the tree instruments the Go runtime. For a worker, goroutine count, GC behaviour and heap growth are exactly the measurements behind "is the worker keeping up", which #526 names as a question an operator asks during an incident and cannot currently answer. go.opentelemetry.io/contrib/instrumentation/runtime supplies it. This also complements #524's profiling assessment, which deferred continuous profiling: runtime metrics are the cheap always-on signal that tells you whether you need a profile at all.

The authoring guide (https://opentelemetry.io/docs/specs/semconv/how-to-write-conventions/). Not a convention to adopt but the method for writing our own flowstate.* ones, which is precisely what #537 proposes generating from the schema. Follow it there rather than inventing house style.

Naming, attributes, recording errors. Covered in #537. Recording errors is the one with an immediate consequence: #531 fixed a leak by recording a classification instead of a raw error, and the convention has an error.type shape our classification should be checked against, so an operator's existing tooling understands it.

Not ours, with reasons

Feature flags (https://opentelemetry.io/docs/specs/semconv/feature-flags/feature-flags-events/). We have editions and policies, not feature flags. An edition is a language version an author opts into and flow fix migrates; a policy is a deployment decision enforced fail-closed. Neither is a runtime toggle evaluated per request, which is what the convention describes. Adopting it would mislabel both.

CI/CD (https://opentelemetry.io/docs/specs/semconv/cicd/). Describes a CI system reporting on its own pipelines. We are not one. There is a tangential use, our own GitHub Actions emitting this about the repo's builds, but that is repository tooling rather than the product, and the deep tier already reports what we need by filing issues.

FaaS (https://opentelemetry.io/docs/specs/semconv/faas/). Models a function-as-a-service invocation. A durable workflow step is not that: it is replayed, compensated, retried under a policy, and outlives any single invocation. The vocabulary would fit badly and imply lifecycle semantics we do not have.

Session (https://opentelemetry.io/docs/specs/semconv/general/session/). Models a client-side user session. Checked and does not apply.

The rule this triage implies

Prefer an existing convention wherever the meaning genuinely matches, because an operator's dashboards and alerts already understand it. Invent a flowstate.* convention only where our domain has no equivalent, which is most of the interesting parts: runs, steps, compensation, triggers, editions. And never adopt a convention by analogy, since the cost of a wrong label is paid by whoever trusts it at three in the morning.

Related

• #522 umbrella
• #537 declaring our own conventions in the schema and generating the rest
• #523 trace propagation, where the RPC conventions already in place matter
• #524 profiling, which runtime metrics complement
• #526 metrics, where "is the worker keeping up" is currently unanswerable

Start by reading the OpenTelemetry wiring in cmd/flow/main.go:720, cmd/flow/serverdev.go:724, cmd/flow/client.go:143, and cmd/flow/telemetry.go, then compare it with the conventions linked in the issue and related work in #523, #526, and #537. Done means recording which conventions apply, which do not, and routing any implementation or schema work to the appropriate follow-up.