fix(otel): replace gen_ai.provider.name with gen_ai.system + engine-to-system mapping (#29204)

Author: Copilot

actions/setup/js/send_otlp_span.cjs

@@ -20,6 +20,26 @@ const { getErrorMessage } = require("./error_helpers.cjs");
  * - No third-party dependencies: uses only Node built-ins + native fetch.
  */
 
+// ---------------------------------------------------------------------------
+// OTel GenAI engine-to-system mapping
+// ---------------------------------------------------------------------------
+
+/**
+ * Maps gh-aw internal engine IDs to the OTel GenAI semantic-convention
+ * `gen_ai.system` values expected by Grafana, Datadog, Honeycomb, and Sentry.
+ * Unknown engines fall back to the engine ID as-is.
+ *
+ * Uses Object.create(null) to avoid prototype-pollution risks from keys like
+ * "constructor" or "__proto__" returning unexpected non-string values.
+ * @type {Record<string, string>}
+ */
+const ENGINE_TO_SYSTEM_MAP = Object.assign(Object.create(null), {
+  copilot: "github_models",
+  claude: "anthropic",
+  codex: "openai",
+  gemini: "google_vertex_ai",
+});
+
 // ---------------------------------------------------------------------------
 // Low-level helpers
 // ---------------------------------------------------------------------------
@@ -913,9 +933,14 @@ async function sendJobConclusionSpan(spanName, options = {}) {
     // All gh-aw agent executions are chat-style LLM completions.
     agentAttributes.push(buildAttr("gen_ai.operation.name", "chat"));
     if (model) agentAttributes.push(buildAttr("gen_ai.request.model", model));
-    // Emit gen_ai.provider.name when engineId is available; it may be omitted when
-    // engine metadata is unavailable, so this span does not guarantee full GenAI spec compliance.
-    if (engineId) agentAttributes.push(buildAttr("gen_ai.provider.name", engineId));
+    // gen_ai.system is the OTel GenAI standard attribute for the LLM system/provider.
+    // Map the gh-aw internal engine ID to the standardized value so backends can apply
+    // native GenAI dashboard detection. The original engine ID is preserved in gh-aw.engine.
+    if (engineId) {
+      const genAiSystem = ENGINE_TO_SYSTEM_MAP[engineId] || engineId;
+      agentAttributes.push(buildAttr("gen_ai.system", genAiSystem));
+      agentAttributes.push(buildAttr("gh-aw.engine", engineId));
+    }
     // gen_ai.workflow.name identifies the agentic workflow, matching the OTel spec example
     // use-cases (e.g. "multi_agent_rag", "customer_support_pipeline").
     if (workflowName) agentAttributes.push(buildAttr("gen_ai.workflow.name", workflowName));

actions/setup/js/send_otlp_span.test.cjs

@@ -1887,7 +1887,7 @@ describe("sendJobConclusionSpan", () => {
     expect(agentSpan.kind).toBe(3); // SPAN_KIND_CLIENT
   });
 
-  it("includes gen_ai.request.model, gen_ai.provider.name, gen_ai.operation.name and gen_ai.workflow.name on the agent span from aw_info.json", async () => {
+  it("includes gen_ai.request.model, gen_ai.system, gh-aw.engine, gen_ai.operation.name and gen_ai.workflow.name on the agent span from aw_info.json", async () => {
     const mockFetch = vi.fn().mockResolvedValue({ ok: true, status: 200, statusText: "OK" });
     vi.stubGlobal("fetch", mockFetch);
 
@@ -1915,11 +1915,12 @@ describe("sendJobConclusionSpan", () => {
     const attrs = Object.fromEntries(agentSpan.attributes.map(a => [a.key, a.value.stringValue ?? a.value.intValue]));
     expect(attrs["gen_ai.operation.name"]).toBe("chat");
     expect(attrs["gen_ai.request.model"]).toBe("claude-3-5-sonnet-20241022");
-    expect(attrs["gen_ai.provider.name"]).toBe("claude");
+    expect(attrs["gen_ai.system"]).toBe("anthropic");
+    expect(attrs["gh-aw.engine"]).toBe("claude");
     expect(attrs["gen_ai.workflow.name"]).toBe("otel-advisor");
   });
 
-  it("omits gen_ai.request.model, gen_ai.provider.name and gen_ai.workflow.name from the agent span when model, engine_id and workflow_name are absent", async () => {
+  it("omits gen_ai.request.model, gen_ai.system, gh-aw.engine and gen_ai.workflow.name from the agent span when model, engine_id and workflow_name are absent", async () => {
     const mockFetch = vi.fn().mockResolvedValue({ ok: true, status: 200, statusText: "OK" });
     vi.stubGlobal("fetch", mockFetch);
 
@@ -1945,10 +1946,41 @@ describe("sendJobConclusionSpan", () => {
     expect(attrs["gen_ai.operation.name"]).toBe("chat");
     const keys = agentSpan.attributes.map(a => a.key);
     expect(keys).not.toContain("gen_ai.request.model");
-    expect(keys).not.toContain("gen_ai.provider.name");
+    expect(keys).not.toContain("gen_ai.system");
+    expect(keys).not.toContain("gh-aw.engine");
     expect(keys).not.toContain("gen_ai.workflow.name");
   });
 
+  it("uses the raw engine ID as gen_ai.system fallback for unknown engines on the agent span", async () => {
+    const mockFetch = vi.fn().mockResolvedValue({ ok: true, status: 200, statusText: "OK" });
+    vi.stubGlobal("fetch", mockFetch);
+
+    process.env.OTEL_EXPORTER_OTLP_ENDPOINT = "https://traces.example.com";
+    process.env.INPUT_JOB_NAME = "agent";
+
+    const startMs = 1_700_000_000_000;
+    const endMs = 1_700_000_005_000;
+    const statSpy = vi.spyOn(fs, "statSync").mockReturnValue(/** @type {Partial<fs.Stats>} */ { mtimeMs: endMs });
+    const readFileSpy = vi.spyOn(fs, "readFileSync").mockImplementation(filePath => {
+      if (filePath === "/tmp/gh-aw/aw_info.json") {
+        return JSON.stringify({ engine_id: "custom-engine" });
+      }
+      throw Object.assign(new Error("ENOENT"), { code: "ENOENT" });
+    });
+
+    await sendJobConclusionSpan("gh-aw.agent.conclusion", { startMs });
+
+    statSpy.mockRestore();
+    readFileSpy.mockRestore();
+
+    const agentBody = JSON.parse(mockFetch.mock.calls[0][1].body);
+    const agentSpan = agentBody.resourceSpans[0].scopeSpans[0].spans[0];
+    const attrs = Object.fromEntries(agentSpan.attributes.map(a => [a.key, a.value.stringValue ?? a.value.intValue]));
+    // Unknown engine ID falls back to the raw value for gen_ai.system
+    expect(attrs["gen_ai.system"]).toBe("custom-engine");
+    expect(attrs["gh-aw.engine"]).toBe("custom-engine");
+  });
+
   it("includes gen_ai.request.model on the conclusion span when model is set in aw_info.json", async () => {
     const mockFetch = vi.fn().mockResolvedValue({ ok: true, status: 200, statusText: "OK" });
     vi.stubGlobal("fetch", mockFetch);

docs/src/content/docs/reference/frontmatter.md

@@ -887,7 +887,8 @@ The agent span (`gh-aw.agent.agent`) uses [OpenTelemetry GenAI semantic conventi
 |-----------|-------------|
 | `gen_ai.request.model` | Model name used for inference |
 | `gen_ai.operation.name` | Always `"chat"` |
-| `gen_ai.provider.name` | Engine identifier (e.g. `copilot`, `claude`) |
+| `gen_ai.system` | Standardized OTel system name (e.g. `github_models`, `anthropic`, `openai`, `google_vertex_ai`) |
+| `gh-aw.engine` | gh-aw internal engine identifier (e.g. `copilot`, `claude`, `codex`, `gemini`) |
 | `gen_ai.workflow.name` | Workflow name |
 | `gen_ai.usage.input_tokens` | Total input tokens consumed |
 | `gen_ai.usage.output_tokens` | Total output tokens produced |
@@ -897,6 +898,9 @@ The agent span (`gh-aw.agent.agent`) uses [OpenTelemetry GenAI semantic conventi
 > [!NOTE]
 > Prior to v0.70, the agent span used private `gh-aw.*` attribute names (`gh-aw.model`, `gh-aw.tokens.input`, etc.) and `SPAN_KIND_INTERNAL`. These attributes were removed and replaced with the `gen_ai.*` convention above. Update any dashboards or alert rules that reference the old attribute names.
 
+> [!NOTE]
+> Prior to v0.76, the engine was emitted as `gen_ai.provider.name` with the raw gh-aw engine ID. It is now emitted as the standard `gen_ai.system` attribute with a mapped OTel system name, and the raw engine ID is preserved in `gh-aw.engine`.
+
 ## Related Documentation
 
 See also: [Trigger Events](/gh-aw/reference/triggers/), [AI Engines](/gh-aw/reference/engines/), [CLI Commands](/gh-aw/setup/cli/), [Workflow Structure](/gh-aw/reference/workflow-structure/), [Network Permissions](/gh-aw/reference/network/), [Command Triggers](/gh-aw/reference/command-triggers/), [MCPs](/gh-aw/guides/mcps/), [Tools](/gh-aw/reference/tools/), [Imports](/gh-aw/reference/imports/)