Update OpenTelemetry GenAI conventions to latest by github-actions[bot] · Pull Request #18 · jeffhandley/extensions

github-actions · 2026-06-28T09:27:28Z

Draft pending the first release of
open-telemetry/semantic-conventions-genai.
Both conventions are Development stability and unreleased. Merge once they ship in a tagged release.

What this PR implements

Area	Convention	Upstream	Compensating change
`gen-ai`	`gen_ai.request.reasoning.level`	#258	`ReasoningLevel` constant; emit from `ChatOptions.Reasoning.Effort`; test augmented.
`gen-ai`	`document` modality for PDF/OpenXML	#142	`DeriveModalityFromMediaType` returns `"document"` for `application/pdf` and OpenXML MIME types; test augmented.
`gen-ai`	Version reference migration	—	All six OpenTelemetry* files migrated from `Semantic Conventions for Generative AI systems v1.41` to `GenAI Semantic Conventions latest`.
`gen-ai`	`gen_ai.execute_tool.duration` histogram	#201	`GenAI.ExecuteTool.Duration` constants; `CreateGenAIExecuteToolDurationHistogram` factory; `FunctionInvocationProcessor` emits per-call with `gen_ai.tool.name`, `gen_ai.tool.type`, `error.type`; `FunctionInvokingChatClient` + `FunctionInvokingRealtimeClientSession` own the `Meter`; test augmented.
`gen-ai`	`gen_ai.invoke_agent.duration` + `gen_ai.prompt.*` (deferred)	#201 #179	🟢 No `invoke_agent` client; no `ChatOptions` prompt-identity property today.

Validation: build clean (net8.0/net9.0/net10.0, 0 warnings); all tests pass. Supersedes #17.

Upstream scan tracking

Legend: 🔴 implemented · ✅ aligned · 🟡 deferred/watch · 🟢 not applicable

Merged (Unreleased) — scanned ref `e153ed9` (2026-06-26)

PR	Area	Change		Status
#258	`gen-ai`	`gen_ai.request.reasoning.level`	🔴	Implemented in `OpenTelemetryChatClient`.
#289	`gen-ai`	Remove `provider.name` required on `invoke_agent`	✅	No internal `invoke_agent` span emits it.
#162	`gen-ai`	`gen_ai.conversation.compacted` + `CompactionPart`	🟡	No compaction-detection in generic layer.
#142	`gen-ai`	`document` modality	🔴	`OtelMessageSerializer.DeriveModalityFromMediaType`.
#257	`gen-ai`	`gen_ai.system_instructions` text-only	✅	Only `OtelGenericPart` (text) emitted.
#217	`gen-ai`	`top_k` double→int	✅	`ChatOptions.TopK` is `int?`.
#214	`gen-ai`	Relax `provider.name` on metric	✅	Already aligned.
#97	`gen-ai`	`plan` operation name	🟢	No plan-operation client.
#201	`gen-ai`	`gen_ai.execute_tool.duration` histogram	🔴	`FunctionInvocationProcessor`; `OpenTelemetryConsts.GenAI.ExecuteTool.Duration`.
#201	`gen-ai`	`gen_ai.invoke_agent.duration` histogram	🟢	No `invoke_agent` client.
#179	`gen-ai`	`gen_ai.prompt.name/version/variable`	🟢	No `ChatOptions` prompt-identity property; constant deferred.
#321	`gen-ai`	`gen_ai.invoke_agent.duration` in-proc / internal span clarification	🟢	Clarification only — no `invoke_agent` client in this repo.
#322	`gen-ai`	`gen_ai.tool.name` / `gen_ai.tool.type` sampling-relevant on execute_tool; `gen_ai.agent.name` added (agent context); invoke_agent attribute alignment	✅	`gen_ai.tool.name` and `gen_ai.tool.type` already passed as initial tags at activity creation. `gen_ai.agent.name` deferred — no agent-name source in generic layer. invoke_agent changes not applicable.
#330	`gen-ai`	JSON schema annotations for complex attributes (Weaver toolchain)	🟢	Toolchain only — no convention attribute / metric / event changes.

In-flight (open PRs)

PR	Area	Change		Notes
#144	`gen-ai`	`BlobPart.content` optional + `stripped_reason`	🟡	Watch — `OtelBlobPart` serialization.
#143	`gen-ai`	Optional `byte_size` on content parts	🟡	Watch — blob/URI/file part types.
#197	`gen-ai`	Modality/cache/phase token-usage	🟡	Watch — new `gen_ai.usage.*` attributes.
#215	`gen-ai`	Scope of `gen_ai.client.operation.duration`	🟡	Watch — metric recording scope.
#190	`gen-ai`	Context-selection event	🟡	Watch — new event type.
#238 #267	`gen-ai`	`gen_ai.agent.finish_reason` + `time_budget`	🟡	Watch — no agent spans.
#250 #291 #336	`gen-ai`	`invoke_agent` span attributes	🟡	Watch — no invoke_agent spans/client.
#341	`gen-ai`	Rename `workflow.duration`	🟡	Watch — deferred workflow constant.
#350 #270	`gen-ai`	Agent identity model	🟡	Watch — no emission site.
#202 #262 #165	`gen-ai`	Agent metrics/guardrail/threat-detection	🟡	Watch — no agent client.
#188	`gen-ai`	Workflow node convention	🟡	Watch — deferred workflow area.
#98	`gen-ai`	A2A handoff as `execute_tool` span	🟡	Watch — extends execute_tool; could affect `gen_ai.execute_tool.duration`.
#96	`gen-ai`	`gen_ai.token.cache/reasoning` metrics	🟡	Watch — new token-usage breakdowns.
#195	`gen-ai`	A2A protocol semconv	🟡	Watch — new inter-agent conventions.
#185 #184	`gen-ai`	Evaluation operation/spans	🟡	Watch — new operation name.
Other (dotnet#99 dotnet#107 dotnet#126 dotnet#136 dotnet#140 dotnet#242 dotnet#211 dotnet#212 dotnet#216 dotnet#219 dotnet#220 · dotnet#351 dotnet#252 dotnet#164 dotnet#325 dotnet#324 dotnet#283 dotnet#340 dotnet#290 dotnet#328 dotnet#112)	gen-ai/mcp	Provider/metadata/doc clarifications; server-side/reference/chore/deps	🟢	No change needed.

Tracking state

# otel-genai-tracking:begin
Upstream-Repo: open-telemetry/semantic-conventions-genai
Upstream-Scan-Ref: e153ed94728993acd0ee6a958559032ca8b20afe    # +#342,#346-#349 merged since 791c341 (chore/deps only)
Upstream-Scan-Date: 2026-06-28T11:32:43Z
Upstream-Release: none                      # Unreleased; Towncrier fragments under changelog.d/
Core-Semconv-Dependency: v1.42.0             # versions.env SEMCONV_VERSION (core dep, NOT the GenAI version)
DotnetExtensions-Implemented-Version: latest
# otel-genai-tracking:end

Generated by MEAI: Update Otel Gen-AI · 143.2 AIC · ⊞ 12.5K · ◷

Generated by MEAI: Update Otel Gen-AI · 91.8 AIC · ⊞ 12.4K · ◷

The OpenTelemetry GenAI semantic conventions moved from open-telemetry/semantic-conventions (under area:gen-ai) to a dedicated repo, open-telemetry/semantic-conventions-genai. The new repo also hosts mcp, openai, anthropic, aws-bedrock, and azure-ai-inference areas, has no releases yet (CHANGELOG Unreleased is the live view), no area: labels (every PR is in scope), and a GenAI-namespaced schema URL (opentelemetry.io/schemas/gen-ai/X.Y.Z) independent of core semconv. Changes (docs-only, no source code edits): - SKILL.md: new Migration Note + Cross-repo applicability sections; rewritten Input Handling for 4 input shapes (PR refs, CHANGELOG snapshot, date range, releases); In-scope areas table with concrete external repo references; broadened search terms in PR Preflight, Mode 1 spec, Mode 2/3/5; Gotchas updated with transitional version- reference grep regex and area-aware constants bullet. - references/file-inventory.md: pre/post-migration doc-comment wording, transitional grep regex, Provider-specific instrumentation table. - references/historical-releases.md: Migration Note prepended; pointers to new repo CHANGELOG/releases/PRs. - references/change-classification.md: Areas section; Area column added to audit and PR-description tables; example anthropic row reflects cross-repo flagging. - references/implementation-patterns.md: Area placement guidance callout; Pattern 6 rewritten with pre/post wording and one-shot migration guidance. - references/implementation-procedure.md: area-aware nested class bullet. - references/review-checklist.md: §6 transitional grep + wording- migration bullet; §7 area-aware nesting; §8 provider-scope bullet with cross-repo case. - references/prompt-template.md: 4-input-shape Background block; Area column in audit table; cross-repo flagging guidance. - references/pr-description.md: title clarifies independent GenAI version; Area column in PR table; old-repo catch-up linkage. - references/testing-guide.md: Per-area test files section. For provider-specific areas not instrumented in dotnet/extensions (anthropic, aws-bedrock), the skill can be applied in the corresponding SDK repos: anthropics/anthropic-sdk-csharp and the BedrockRuntime service library of aws/aws-sdk-net. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

- SKILL.md Migration Note: drop point-in-time version examples (1.42.0 / v1.41.0 "at the time of writing") in favor of the X.Y.Z placeholder already used elsewhere. - SKILL.md "No releases yet" bullet: remove "as of this writing" and add a TODO marker to remove the framing once the first release ships. - implementation-procedure.md: split the dense constant-location bullet into a mini-list and link the area-placement table in implementation-patterns.md instead of restating areas inline. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Spec URL now resolves to a 'Moved' stub; soften the claim, keep the <see href> for now, and add a TODO to retarget once a canonical URL exists - Note the schema URL (opentelemetry.io/schemas/gen-ai/X.Y.Z) is not yet published; derive the GenAI version from CHANGELOG/versions.env until then - Correct area-classification guidance: only gen-ai, mcp, openai, and aws-bedrock have a model/<area>/ registry; anthropic and azure-ai-inference are docs-only under docs/gen-ai/<provider>.md; all docs live under docs/gen-ai/ - Drop the broken schema-snapshot/ reference from Mode 1 step 4 - Note the new repo uses granular area:* labels (area:mcp, area:inference, etc.) - Apply the same corrections to the In-scope areas table header, change-classification.md, and implementation-patterns.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Self-review follow-ups found while verifying the skill against the live semantic-conventions-genai repo: - versions.env holds only the core semconv dependency (SEMCONV_VERSION, currently v1.42.0) and the Weaver version; it carries no GenAI version. Remove guidance that derived the GenAI version from versions.env and state that, until a GenAI release/schema URL exists, the update is identified by its Unreleased CHANGELOG snapshot (commit/ref/date) - file-inventory.md: drop the stale 'published spec page still resolves and renders the spec' claim; the page is now a 'Moved' stub, so keep the <see href> only until a canonical URL is published and read docs/gen-ai/ and model/<area>/ as the spec source - file-inventory.md / implementation-patterns.md: stop tying the doc-comment version to the unpublished schema URL; replace the v1.42.0 target-wording example (the core semconv version) with vX.Y.Z - pr-description.md: same version-source correction for the PR title Stop referring to a 'new repo' and an 'old repo'. Treat open-telemetry/semantic-conventions-genai as the current conventions repo and refer to open-telemetry/semantic-conventions as the consolidated repo where these conventions were previously managed. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

The semantic-conventions-genai CHANGELOG.md Unreleased section is empty (managed by Towncrier; fragments are compiled into it only at release time), so the live what's-new view is the changelog.d/ news fragments. - SKILL.md: Migration Note describes the Towncrier mechanism and points the what's-new view at changelog.d/ fragments; Input Handling snapshot form, Mode 1 step 4, and Mode 5 step 1 reference changelog.d/ instead of the CHANGELOG.md Unreleased section; intro lists "changelog snapshots". - references/file-inventory.md, implementation-patterns.md, pr-description.md: take the audited GenAI version from the changelog.d/ fragment snapshot. - references/historical-releases.md, prompt-template.md: link/label the changelog.d/ fragments as the snapshot source. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- references/pr-description.md Title: add a `latest` title form ("Update OpenTelemetry GenAI conventions to latest") for the unreleased case (no release and no published schema URL), alongside the versioned form; keep the title as `latest` and pin the changelog.d/ snapshot in the body until a version exists. - references/pr-description.md Description: use `latest` in the Version column and record the changelog.d/ fragment snapshot when no GenAI version number is determined yet. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

references/pr-description.md: add an "Upstream scan tracking tables" subsection defining one shared column set for both the merged-changes table and the in-flight (open-PR) table: `| Upstream PR | Area | Change | Applicability | Status |`. The Applicability column holds the color symbol only; explanatory text goes in the separate Status column. Includes the applicability legend (implemented / aligned / watch / not applicable). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

references/pr-description.md: add guidance that the Change column must use break opportunities (', ' or ' / ' with spaces) instead of long unbroken /-separated runs, which browsers do not wrap and which force the table wider than the viewport. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- pr-description.md: add an "Upstream-scan tracking PR body template" section laying out the body in order -- status note, "What this PR implements" table, the merged and in-flight applicability tables, and the otel-genai-tracking state block as the final section. - Keep the refresh procedure out of the PR body: document it in a "Refreshing the tracking PR" skill section that drives the update-otel-genai-conventions skill (Mode 1 Audit, Input Handling git log diff, change-classification, version-reference migration). - SKILL.md: point "PR Title and Description Guidance" at the full body template; note in Preflight that the tracking PR is the scan record to refresh, not a blocking duplicate. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

… base

Add .github/workflows/meai-update-otel-genai.md (and its compiled lock) that runs daily, plus on manual dispatch, to integrate open-telemetry/semantic-conventions GenAI updates into Microsoft.Extensions.AI and maintain a single draft PR until the upstream release is published. - Invokes the update-otel-genai-conventions skill in Plan-then-Implement mode, comparing upstream HEAD against this repo''s main. - Relies on the skill''s change-classification reference to classify each upstream change as actionable-now (code/minor action on an already-emitted item) vs deferred (constant not yet emitted, no client, server-side, doc-only), and adds a lifecycle invariant so deferral never collapses a run into a no-op -- deferred items still keep a maintained draft PR open. - Finds the workflow''s PR by content (automation + area-ai labels plus the otel-genai-tracking state block), never by branch name, then chooses an action from PR state plus an upstream-SHA comparison: caught-up open/merged is a no-op; behind-open-draft does an incremental push to the PR''s existing head branch; behind-non-draft leaves an advisory comment; merged-but-behind and any closed-without-merge PR (caught up or behind) start a fresh PR; a still-open prior published-version PR gets only an advisory comment. - Defers the PR title, target token, and full PR body (status note, what-this-implements table, upstream-scan applicability tables, and the otel-genai-tracking state block) to the skill''s pr-description reference: the target is `latest` while the conventions are unreleased and a concrete v{version} once a release/schema publishes. Fresh PRs use a unique, run-scoped branch update-otel-genai-to-{target}-{GITHUB_RUN_ID} so they never collide with a branch a closed PR left behind; labeled automation and area-ai; retitles the PR when the skill''s target resolves to a version; marks it ready for review once the upstream release is published. - Records the upstream-scan tracking state as a fenced yaml block whose first/last lines are `# otel-genai-tracking:begin`/`:end` sentinel comments inside the code fence (gh-aw safe-output processing strips HTML comments), and finds the maintained PR by the automation/area-ai labels plus that block; the skill pr-description template matches. - Restricts edits to src/test/docs/samples for Microsoft.Extensions.AI via allowed-files; commits on the checked-out HEAD without creating the PR branch locally so patch generation diffs against the exact checkout SHA. - No-op runs write the reason to the step summary and emit no issue, comment, or report; failures are not reported as issues; threat detection is disabled (the sandbox, read-only permissions, and file allow-list already constrain the run); at most one comment is posted per run. - Guards execution with an if condition so it only runs on dispatch or on the canonical (non-fork) repository, and uses the Copilot PAT pool. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…-genai ref Add an optional `upstream_ref` workflow_dispatch input to the MEAI: Update Otel Gen-AI workflow so a manual dispatch can scan a specific ref of open-telemetry/semantic-conventions-genai instead of the default-branch HEAD. - Declare the input in the workflow_dispatch frontmatter (git ref -- branch, tag, or commit SHA; optional string; empty by default). - Wire it into Step 1 via `${{ github.event.inputs.upstream_ref }}`: a non-empty value is scanned as the upstream ref, while an empty value (every scheduled run, and dispatches that leave it blank) scans the default-branch HEAD. The resolved commit SHA flows into Upstream-Scan-Ref and all downstream SHA comparisons. - Generalize the "upstream HEAD" wording to "scanned upstream commit/SHA" across Steps 2, 3, and 5 and the no-op rules so the language matches an overridable scan ref. - Recompile the lock (gh-aw v0.80.9). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Add ReasoningLevel constant to OpenTelemetryConsts.GenAI.Request - Emit gen_ai.request.reasoning.level from ChatOptions.Reasoning.Effort (lowercased enum name) in OpenTelemetryChatClient - Augment ExpectedInformationLogged_Async test with Reasoning option and gen_ai.request.reasoning.level assertion - Refactor DeriveModalityFromMediaType to check IsDocumentMediaType before top-level type parsing Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-06-28T10:46:28Z

Commit pushed: 7008a2e

Generated by MEAI: Update Otel Gen-AI · 289.1 AIC · ⊞ 12.5K

…entions-genai#201) - Add GenAI.ExecuteTool.Duration metric constants (Name, Description, ExplicitBucketBoundaries) to OpenTelemetryConsts.cs - Add CreateGenAIExecuteToolDurationHistogram factory to OtelMetricHelpers.cs - FunctionInvocationProcessor accepts optional Histogram<double>? and emits gen_ai.execute_tool.duration on each function call with gen_ai.tool.name, gen_ai.tool.type, and error.type (on failure) tags - FunctionInvokingChatClient and FunctionInvokingRealtimeClientSession create/own/dispose a Meter and Histogram, wiring it to FunctionInvocationProcessor - Augment FunctionInvocationTrackedWithActivity test to assert on the execute_tool duration metric - Fix stale 'v1.41' wording in custom Realtime attributes doc-comment Deferred (no emission site): - gen_ai.invoke_agent.duration (PR dotnet#201): no invoke_agent client in this repo - gen_ai.prompt.name/version/variable (PR dotnet#179): no ChatOptions property to emit from Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-06-28T11:12:29Z

Commit pushed: 617d0fc

Generated by MEAI: Update Otel Gen-AI · 533.6 AIC · ⊞ 12.5K

github-actions · 2026-06-28T11:26:16Z

Upstream scan update — ref 791c341 (2026-06-25)

Three new upstream changes merged since the last scan (0183a25, 2026-06-23):

PR	Change	Assessment
#321	`gen_ai.invoke_agent.duration` in-proc / internal span clarification	🟢 Not applicable — no `invoke_agent` client
#322	`gen_ai.tool.name` / `gen_ai.tool.type` sampling-relevant on execute_tool; `gen_ai.agent.name` added (agent context); invoke_agent attribute alignment	✅ tool name/type already passed as initial activity tags; `gen_ai.agent.name` deferred (no agent-name source); invoke_agent changes not applicable
#330	JSON schema annotations for complex attributes (Weaver toolchain)	🟢 Toolchain only — no convention attribute/metric/event changes

No code changes required. PR body updated with new scan reference.

Generated by MEAI: Update Otel Gen-AI · 143.2 AIC · ⊞ 12.5K · ◷

jeffhandley and others added 16 commits May 7, 2026 22:44

Apply suggestions from code review

44b2b9d

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Merge otel-repo-move standalone semconv-genai skill into the workflow…

d5c42bc

… base

Initialize gh-aw for agentic workflows

d413318

Set up the PAT pool for agentic workflows

f9a3714

Update OpenTelemetry GenAI conventions to latest

a2730ff

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions Bot added area-ai automation labels Jun 28, 2026

jeffhandley force-pushed the main branch from 0713297 to afe056c Compare June 28, 2026 10:01

jeffhandley mentioned this pull request Jun 28, 2026

Update OpenTelemetry GenAI conventions to latest #19

Closed

jeffhandley force-pushed the main branch from afe056c to 83d53d2 Compare June 28, 2026 10:31

jeffhandley force-pushed the main branch from 83d53d2 to dd752c3 Compare July 1, 2026 17:40

Navigation Menu

Update OpenTelemetry GenAI conventions to latest - #18

Update OpenTelemetry GenAI conventions to latest#18
github-actions[bot] wants to merge 18 commits into
mainfrom
update-otel-genai-to-latest-28317203007

github-actions Bot commented Jun 28, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 28, 2026

Uh oh!

github-actions Bot commented Jun 28, 2026

Uh oh!

github-actions Bot commented Jun 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

github-actions Bot commented Jun 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this PR implements

Upstream scan tracking

Merged (Unreleased) — scanned ref e153ed9 (2026-06-26)

In-flight (open PRs)

Tracking state

Uh oh!

github-actions Bot commented Jun 28, 2026

Uh oh!

github-actions Bot commented Jun 28, 2026

Uh oh!

github-actions Bot commented Jun 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

github-actions Bot commented Jun 28, 2026 •

edited

Loading

Merged (Unreleased) — scanned ref `e153ed9` (2026-06-26)