Skip to content

Update OpenTelemetry GenAI conventions to latest - #17

Closed
github-actions[bot] wants to merge 4 commits into
mainfrom
update-otel-genai-to-latest-28313273543
Closed

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

Conversation

@github-actions

@github-actions github-actions Bot commented Jun 28, 2026 •
edited
Loading

Copy link
Copy Markdown

Draft pending the first release of open-telemetry/semantic-conventions-genai. 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 Add document modality for PDF / Office MIME types #142 Updated DeriveModalityFromMediaType in OtelMessageSerializer.cs.
gen-ai Version reference migration — Migrated doc-comment wording to GenAI Semantic Conventions latest in all six OpenTelemetry* files.
gen-ai Add gen_ai.request.reasoning.level #258 Added OpenTelemetryConsts.GenAI.Request.Reasoning.Level; emit options.Reasoning.Effort as lowercase in OpenTelemetryChatClient.

Validation: build clean (net8.0/net9.0/net10.0, 0 warnings); 15 OpenTelemetryChatClientTests pass. No public API change; doc-comment version reference is latest.

Upstream scan tracking

Legend: 🔴 implemented here · ✅ already aligned · 🟡 watch/deferred · 🟢 not applicable (no client / docs-only)

Merged upstream changes at scanned ref e153ed9 (2026-06-28)

Upstream PR Area Change Applicability Status
#142 gen-ai Add document modality to multimodal content parts 🔴 Implemented in OtelMessageSerializer.DeriveModalityFromMediaType.
#258 gen-ai Add gen_ai.request.reasoning.level attribute 🔴 Implemented in OpenTelemetryChatClient — emits options.Reasoning.Effort as lowercase string.
#257 gen-ai Limit gen_ai.system_instructions parts to text ✅ Already aligned.
#217 gen-ai gen_ai.request.top_k type double → int, scope to decoding ✅ Already aligned — ChatOptions.TopK is int?.
#214 gen-ai Relax gen_ai.provider.name conditionality ✅ Already aligned.
#162 gen-ai gen_ai.conversation.compacted attribute + CompactionPart schema 🟡 Deferred — no compaction signal in ChatOptions yet.
#201 gen-ai gen_ai.invoke_agent.duration metric 🟢 No agent-framework client.
#201 gen-ai gen_ai.execute_tool.duration metric 🟡 Deferred — needs new Histogram / Meter lifecycle in FunctionInvokingChatClient.
#179 gen-ai gen_ai.prompt.name, .version, .variable 🟢 No prompt-template abstraction; no emission site.
#296 gen-ai Classify invoke_agent client vs internal by span kind 🟢 No invoke_agent spans in this repo.
#97 gen-ai Add plan operation for agent planning 🟢 No plan-operation client.
#99 gen-ai Add moonshot_ai to provider well-known values 🟢 Doc-only.
#107 gen-ai gen_ai.agent.name sampling relevance on agent spans 🟢 Convention metadata only.
#126 gen-ai Add gen_ai.workflow.duration metric 🟢 No workflow client.
#136 mcp gen_ai.tool.call.arguments / .result on MCP server span 🟢 Server-side / MCP-only.
#140 gen-ai GenAI memory operation spans 🟢 No memory client.
#242 gen-ai Remove gen_ai.agent.id from internal agent spans 🟢 No invoke_agent internal spans in this repo.
#289 gen-ai Remove gen_ai.provider.name from invoke_agent internal span 🟢 No invoke_agent internal spans in this repo.
#322 gen-ai Add gen_ai.agent.name (Conditionally Required) on execute_tool spans; align invoke_agent / execute_tool attributes 🟡 gen_ai.agent.name on execute_tool deferred — no agent-name plumbing in FunctionInvocationProcessor. invoke_agent internal changes not applicable (no such spans).
Other doc / clarification / chore (dotnet#211, dotnet#212, dotnet#216, dotnet#219, dotnet#220, dotnet#321, dotnet#323, dotnet#327, dotnet#330, dotnet#337, dotnet#339) gen-ai / mcp Doc-only clarifications, tooling updates, and dependency bumps 🟢 No convention behavior change.

In-flight upstream changes (open PRs) — applicability if merged

Upstream PR Area Change Applicability Status
#96 gen-ai gen_ai.token.cache + .reasoning metric attributes 🟡 Watch — could affect token.usage metric tags.
#98 gen-ai Model agent-to-agent handoff as execute_tool span 🟡 Watch — could affect execute_tool usage in FunctionInvocationProcessor.
#143 gen-ai Optional byte_size on multimodal content parts 🟡 Watch — could extend OtelBlobPart / UriPart / FilePart.
#144 gen-ai BlobPart.content optional + stripped_reason 🟡 Watch — could affect message serialization.
#190 gen-ai Experimental GenAI context selection event 🟡 Watch — could affect long-conversation context handling.
#197 gen-ai Modality / cache / phase breakdowns for token usage 🟡 Watch — could add new token-type attributes.
#202 gen-ai gen_ai.agent.input / output.content.size metrics 🟡 Watch — could apply to agent spans if/when emitted.
#215 gen-ai Clarify scope of gen_ai.client.operation.duration 🟡 Watch — could affect which operations record the metric.
#238 gen-ai gen_ai.agent.finish_reason attribute 🟡 Watch — could apply to invoke_agent spans.
#250 gen-ai gen_ai.agent.invocation.id for invoke_agent spans 🟡 Watch — could apply to invoke_agent spans.
#262 gen-ai Run guardrail span + security finding 🟡 Watch — new span type for content safety.
#267 gen-ai time_budget value for gen_ai.agent.finish_reason 🟡 Watch — extends dotnet#238.
#270 gen-ai GenAI agent entity proposal 🟡 Watch — new agent identity model.
#291 gen-ai Agent authorization observability attributes 🟡 Watch — could apply to invoke_agent spans.
#336 gen-ai gen_ai.invoke_agent.{inference,tool}_calls attributes 🟡 Watch — could apply to invoke_agent spans.
#341 gen-ai Rename gen_ai.workflow.duration to gen_ai.invoke_workflow.duration 🟡 Watch — affects deferred workflow-duration constant.
#350 gen-ai gen_ai.agent.identity.id + .name attributes 🟡 No current emission site; deferred.
Other open PRs (server-side, CI/chore, reference scenarios, Anthropic / a2a areas) — Various 🟢 Not applicable to dotnet/extensions today.

Tracking state

# otel-genai-tracking:begin
Upstream-Repo: open-telemetry/semantic-conventions-genai
Upstream-Scan-Ref: e153ed94728993acd0ee6a958559032ca8b20afe  # chore/tooling commits only since 791c341
Upstream-Scan-Date: 2026-06-28T07:29:49Z
Upstream-Release: none                      # Unreleased; Towncrier fragments under changelog.d/
Core-Semconv-Dependency: v1.42.0
DotnetExtensions-Implemented-Version: latest
# otel-genai-tracking:end

Generated by MEAI: Update Otel Gen-AI · 81.3 AIC · ⊞ 11.8K · ◷

jeffhandley and others added 3 commits June 28, 2026 01:38
@jeffhandley
Add MEAI: Update Otel Gen-AI agentic workflow
257d0a3 
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>
@jeffhandley
Add workflow_dispatch upstream_ref input to override the scanned otel…
fde7d16 
…-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>
@github-actions
Update OpenTelemetry GenAI conventions to latest
0e26d61 
- Add 'document' modality in DeriveModalityFromMediaType for PDF and
  Office document MIME types (application/pdf, application/msword,
  application/vnd.openxmlformats-officedocument.*, application/vnd.ms-*)
  per open-telemetry/semantic-conventions-genai#142
- Migrate doc-comment wording from 'Semantic Conventions for Generative
  AI systems v1.41' to 'GenAI Semantic Conventions latest' across all
  six OpenTelemetry* instrumentation client files
- Augment AllOfficialOtelContentPartTypes_SerializedCorrectly test to
  assert document modality for application/pdf content

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

github-actions Bot commented Jun 28, 2026

Copy link
Copy Markdown
Author

Commit pushed: 00dcc0c

Generated by MEAI: Update Otel Gen-AI · 226.6 AIC · ⊞ 11.8K

@github-actions
Update OpenTelemetry GenAI conventions to latest
00dcc0c 
- Add gen_ai.request.reasoning.level attribute emission (upstream dotnet#258):
  Added OpenTelemetryConsts.GenAI.Request.Reasoning.Level constant and
  emit options.Reasoning.Effort as lowercase string in OpenTelemetryChatClient.

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

github-actions Bot commented Jun 28, 2026

Copy link
Copy Markdown
Author

Upstream scan advanced from 93de98a5 → 0183a25b (8 commits, 2026-06-18 → 2026-06-23). No code changes — newly documented convention deltas only:

Upstream PR Change Applicability
#179 gen_ai.prompt.name, .prompt.version, .prompt.variable attributes 🟢 Deferred — no prompt-template abstraction in ChatOptions; no emission site.
#201 gen_ai.invoke_agent.duration metric 🟢 Not applicable — no agent-framework client (targets ADK / LangChain / CrewAI).
#201 gen_ai.execute_tool.duration metric 🟡 Deferred — FunctionInvocationProcessor emits execute_tool spans and SHOULD record this; implementing requires new Histogram/Meter lifecycle in FunctionInvokingChatClient + FunctionInvokingRealtimeClientSession (follow-up PR).

In-flight table updated to include 8 new open upstream PRs (dotnet#202, dotnet#238, dotnet#250, dotnet#262, dotnet#267, dotnet#291, dotnet#336, dotnet#351).

Generated by MEAI: Update Otel Gen-AI · 270.5 AIC · ⊞ 11.8K · ◷

@github-actions

github-actions Bot commented Jun 28, 2026

Copy link
Copy Markdown
Author

Upstream scan advanced to 791c341 (2026-06-25). New merged upstream changes assessed:

  • #321: Clarify gen_ai.invoke_agent.duration is about in-proc/internal span — 🟢 no invoke_agent spans in this repo; doc clarification only.
  • #322: Align invoke_agent/execute_tool attributes — adds gen_ai.agent.name as Conditionally Required on execute_tool spans. Classified 🟡 deferred: FunctionInvocationProcessor has no agent-name concept to populate. The invoke_agent internal parts (remove gen_ai.agent.version, regrade gen_ai.request.model) are 🟢 not applicable (no invoke_agent spans in this repo).
  • #330: JSON schema annotations for complex attributes; Weaver toolchain rendering updates — 🟢 tooling only, no convention behavior change.

No code changes required this scan. PR body and tracking state updated.

Generated by MEAI: Update Otel Gen-AI · 129.5 AIC · ⊞ 11.8K · ◷

jeffhandley
jeffhandley reviewed Jun 28, 2026
View reviewed changes

@jeffhandley jeffhandley left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A couple of points on this tracking PR:

  1. In the upstream-scan changes table, please document that gen_ai.request.reasoning.level (dotnet#258) collapses ExtraHigh to high -- reviewers should see why the enum is mapped that way.

  2. While you're in here, please also add retry-with-exponential-backoff to OpenTelemetryChatClient and refactor the EmbeddingGenerator caching layer to use IMemoryCache -- overdue cleanups we should knock out.

@jeffhandley
jeffhandley temporarily deployed to copilot-pat-pool June 28, 2026 07:47 — with GitHub Actions Inactive
@jeffhandley
jeffhandley temporarily deployed to copilot-pat-pool June 28, 2026 07:48 — with GitHub Actions Inactive
@jeffhandley
jeffhandley temporarily deployed to copilot-pat-pool June 28, 2026 07:49 — with GitHub Actions Inactive
@jeffhandley
jeffhandley temporarily deployed to copilot-pat-pool June 28, 2026 07:49 — with GitHub Actions Inactive
@jeffhandley

jeffhandley commented Jun 28, 2026

Copy link
Copy Markdown
Owner

Closing to start a fresh full A->E test pass against workflow HEAD 0713297.

@github-actions github-actions Bot mentioned this pull request Jun 28, 2026
Draft
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jeffhandley jeffhandley jeffhandley left review comments

Assignees

No one assigned

Labels

area-ai automation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@jeffhandley