SKIP TO CONTENT
AI AGENTS6 minAgents in Production / Ep. 12 · Stage 12-4

GenAI Conventions: How to Pin a Version With No Release

The GenAI conventions have no release you can name. So which version does your telemetry follow, and how would anyone reading it know?

XIN
Pixel-art night scene of a ship’s chart table under a lamp. Glowing thread lines run between small robot figures on the map, and a brass pin holds the chart down while the sea outside the window shifts.

IN 30 SECONDS

Pinning is locking your setup to one exact version. For the GenAI conventions, with no release, that means core v1.44.0 plus one full commit of semantic-conventions-genai, written on every signal, with pure renames handled in the Collector.

KEY TAKEAWAYS · 3

  • Pin the core conventions at v1.44.0 and the GenAI repository at a full commit SHA, and write both on every resource.
  • Handle pure renames in the Collector. A change to a metric’s type or dimensions, like #374, needs instrumentation work.
  • Move the pin on purpose: read the breaking fragments, run old and new names side by side, then change the SHA.
On this page

Sort every field before you pin

IN SHORT Pin core at v1.44.0 and the GenAI repository at a full commit SHA, stamp both on every signal, and move the pin only on purpose.

WORDS TO KNOW

Pin
Locking your setup to one exact version, here a full git commit SHA: the unique id of one saved snapshot of the code.
Resource
In OpenTelemetry, the attributes that describe what sends the telemetry, such as service.name. They travel with every span, metric and log.
Collector
The OpenTelemetry Collector, a service that receives telemetry on its way to your backend and can rename or reshape it.
Dimension
A label you can group a metric’s numbers by, such as text, image or audio.

Pinning a spec with no releases sounds odd until you remember git. To Pin Locking your setup to one exact version, here a full git commit SHA: the unique id of one saved snapshot of the code. See the glossary to a commit SHA is to pick an exact snapshot: a release without the label.

Before pinning, sort every field you emit into one of four buckets. Never make up a gen_ai.* key for data the spec doesn’t cover.

WHERE DOES THIS FIELD GO
Decide: What kind of field is this?Decision tree: What kind of field is this? If Stable in the core conventions (error.type, server.address, server.port), then Depend on it. If A gen_ai.* name you chart, alert or bill on, then Use it, pinned to a commit. If No gen_ai.* equivalent (decision, review, retention), then Your com.acme.* namespace. If Content: messages, instructions, tool arguments, then Off by default.DECIDEWhat kind of field is this?If stable in the coreconventions (error.type,server.address,server.port)Depend on itPinned with core v1.44.0If a gen_ai.* name youchart, alert or bill onUse it, pinned to acommitStill Development; purerenames handled in theCollectorIf no gen_ai.* equivalent(decision, review,retention)Your com.acme.*namespacecom.acme stands for yourreverse domain, as thenaming guide advises. Nevera made-up gen_ai.* keyIf content: messages,instructions, toolargumentsOff by defaultRecommended: store itoutside when volume orsensitive data call for it.Point to it from the span
My triage. The rose branch is the one teams skip, and it’s the one that hurts when the spec catches up.

Coming up next: So how do you pin a spec that has no release?

Six steps to pin, and to move the pin

IN SHORT Two pins written on every signal, and one Collector rule per pure rename. This is the procedure I’d put in the repo.

THE PIN, STEP BY STEP

Flow diagram: 6 stepsFlow diagram: 6 steps. Pin core at v1.44.0, then Pin the GenAI repo to a full commit. Pin the GenAI repo to a full commit, then Write both on the resource. Write both on the resource, then Pin the library, read its opt-in settings. Pin the library, read its opt-in settings, then Rename in the Collector, not in agent code. Rename in the Collector, not in agent code, then Move the pin on purpose. Move the pin on purpose loops back to Pin the GenAI repo to a full commit.1Pin core at v1.44.02Pin the GenAI repo toa full commit3Write both on theresourceOn every signal4Pin the library, readits opt-in settings5Rename in theCollector, not inagent code6Move the pin onpurposeRead the breaking changesfirst

Step 1. Pin core. Pin the core conventions at v1.44.0, the version the GenAI manifest depends on. It holds the stable error.type and server.* attributes.

Pick a step to see it move
  1. Pin core Pin the core conventions at v1.44.0, the version the GenAI manifest depends on. It holds the stable error.type and server.* attributes.
  2. Pin the GenAI repo Pin semantic-conventions-genai to a full commit SHA. There are no tags, and the schema URL is a -dev placeholder.
  3. Stamp the resource Write both pins on the resource, for example com.acme.semconv.core and com.acme.semconv.genai_commit.
  4. Pin the library Pin the instrumentation library too, and read what its opt-in settings actually do.
  5. Rename in the Collector Each pure rename gets one rule, versioned with the pin. Type or dimension changes go back to the instrumentation.
  6. Re-pin on purpose Read the new breaking changelog.d fragments, run old and new names side by side for a while, then move the SHA.
Step 6 loops back to step 2: moving the pin is a deliberate change with a diff, never a side effect of upgrading a library.

For step 4, core v1.41.0 and its v1.41.1 patch had a transition plan. Libraries that already sent old GenAI names should keep them by default, and switch only when gen_ai_latest_experimental was among the values of OTEL_SEMCONV_STABILITY_OPT_IN.

WATCH OUT

I didn’t find that text in the new repository at the commit I read, so check what your library documents instead of assuming.

Step 5 is the one I care about most. Take a fleet the size of the 46 agents I ran at Integra: a rename in agent code means many separate changes. In the Collector The OpenTelemetry Collector, a service that receives telemetry on its way to your backend and can rename or reshape it. See the glossary, it’s one reviewed change, and dashboards keep their queries.

IN PLAIN WORDS

That only works for a true rename, like #440’s cache field. #374 swapped one histogram for counters and per-operation histograms, with a new modality Dimension A label you can group a metric’s numbers by, such as text, image or audio. See the glossary. No Collector rule can invent a dimension the instrumentation never sent.

Changes like that need new instrumentation, and a check that the totals still match. The pin on the Resource In OpenTelemetry, the attributes that describe what sends the telemetry, such as service.name. They travel with every span, metric and log. See the glossary tells you which spans came before.

“SHOULD NOT be used in production.”

OpenTelemetry maturity levels, on Development

That’s the maturity definition for Development status, whose configuration might break often. If you use it anyway, and most of us will, this procedure is the price of doing it with care.

ITEM GET

Pin, stamp, rename once

Two pins on every signal, and each pure rename as one Collector rule versioned with them.

Sources, read on 7 October 2026: semantic-conventions-genai, manifest, core v1.41.0 README, spans, maturity levels.

FAQ

OpenTelemetry says a Development component’s configuration might break often, and that it SHOULD NOT be used in production. Teams use these names anyway. As far as I know, nothing else gives agent telemetry a shared vocabulary.

STAGE CLEAR

What you now know

  • Which four kinds of fields there are, and where each one goes before you pin.
  • Why a Collector rule can fix a rename but not a new dimension.

Check yourself

Tap or click a question to see the answer.

Your cost report still reads gen_ai.usage.cache_creation.input_tokens, which #440 renamed to gen_ai.usage.cache_write.input_tokens. Is a Collector rule enough?

Yes, for this pure rename: one rule, versioned with the pin, maps the new key back. #374 was different, because it changed a metric’s type and dimensions.

You finished every stage published so far in this series. Back to the series map

Adam Boudjemaa
Adam Boudjemaa

Web3 x AI engineer, former CTO of Integra. Named author (1 of 5) of ERC-3643, first author of ERC-6960, co-author of ERC-7410, and co-author of ERC-8203, which is still a draft.

Have a project to ship or a role to fill?

Discuss your project or role

My work at the web3 x AI intersectionOpen-source tools I build

LinkedInTwitterGitHub
Follow the engineering notes

Get new articles on production AI and smart contracts by email.