Add agent diagnostic telemetry vocabulary

Directory.Build.props

@@ -7,14 +7,12 @@
   </PropertyGroup>
 
   <PropertyGroup Label="Versioning">
-    <!-- Development fallback for the Qyl.Telemetry.* family: the new package IDs are born
-         at 1.0.0 stable — this is the launch refactor, so they do not stage through a
-         prerelease band. The release workflow stamps the published version from the tag;
-         this value is what a local or CI build produces, and the v1.0.0 tag is the human
-         act that publishes it. No VersionSuffix default, so a build is stable unless one
-         is passed explicitly (-p:VersionSuffix=rc.1). The frozen Qyl.OpenTelemetry.* IDs
-         keep their own 4.0.0 on nuget.org until they are unlisted. -->
-    <VersionPrefix Condition="'$(VersionPrefix)' == ''">1.0.0</VersionPrefix>
+    <!-- Development fallback for the current Qyl.Telemetry.* release line. The release
+         workflow stamps the published version from the tag; this value is what a local or
+         CI build produces. No VersionSuffix default, so a build is stable unless one is
+         passed explicitly (-p:VersionSuffix=rc.1). The frozen Qyl.OpenTelemetry.* IDs keep
+         their own 4.0.0 on nuget.org until they are unlisted. -->
+    <VersionPrefix Condition="'$(VersionPrefix)' == ''">4.2.0</VersionPrefix>
     <Version Condition="'$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix)</Version>
     <Version Condition="'$(VersionSuffix)' == ''">$(VersionPrefix)</Version>
   </PropertyGroup>

README.md

@@ -22,15 +22,14 @@ dotnet add package Qyl.Telemetry.SemanticConventions
 ```
 
 The three supported packages are published on
-[nuget.org](https://www.nuget.org/profiles/ANcpLua) at `1.0.0`. `.Analyzers` is
+[nuget.org](https://www.nuget.org/profiles/ANcpLua); this change targets `4.2.0`. `.Analyzers` is
 preview-only and is not among them. Incubating APIs intentionally track unstable
 upstream conventions and may change between minor releases.
 
 **Coming from `Qyl.OpenTelemetry.SemanticConventions`?** These are new package IDs, not
 new versions of the old ones. The `Qyl.OpenTelemetry.SemanticConventions*` IDs stop at
-`4.0.0` and receive no further releases; change the ID and take `1.0.0`. The lower number
-is not a downgrade — the new family starts its own version line, and the generated
-namespace ships as its birth ABI rather than as a break to anything already published.
+`4.0.0` and receive no further releases; change to the `Qyl.Telemetry.*` family. The new
+family began at `1.0.0` and now follows its own monotonic release line.
 
 ## Choosing between the compiled packages and the source generator
 

Version.props

@@ -13,7 +13,7 @@
     <XunitVersion>3.2.2</XunitVersion>
     <AwesomeAssertionsVersion>9.4.0</AwesomeAssertionsVersion>
 
-    <NuGetPackagingVersion>7.6.0</NuGetPackagingVersion>
+    <NuGetPackagingVersion>7.9.0</NuGetPackagingVersion>
     <SystemSecurityCryptographyXmlVersion>10.0.10</SystemSecurityCryptographyXmlVersion>
   </PropertyGroup>
 </Project>

eng/semconv/attributes.lock.sha256

@@ -1 +1 @@
-61af43292e106cab4cf587603c2c9cbb6da60b8ad4f17daef88a393e9a8333b9
+de15808eede6e525c3deaf61b5709204dc0bf68ee6b5f05c426559843494ca8a

src/Qyl.Telemetry.SemanticConventions.Analyzers/SemconvRegistryFacts.g.cs

@@ -793,6 +793,15 @@ internal static class SemconvRegistryFacts
             ["process.vpid"] = SemconvAttributeValueKind.Integer,
             ["process.working_directory"] = SemconvAttributeValueKind.String,
             ["profile.frame.type"] = SemconvAttributeValueKind.String,
+            ["qyl.agent.diagnostic.check.count"] = SemconvAttributeValueKind.Integer,
+            ["qyl.agent.diagnostic.check.failed_count"] = SemconvAttributeValueKind.Integer,
+            ["qyl.agent.diagnostic.extension.id"] = SemconvAttributeValueKind.String,
+            ["qyl.agent.diagnostic.format.version"] = SemconvAttributeValueKind.Integer,
+            ["qyl.agent.diagnostic.outcome"] = SemconvAttributeValueKind.String,
+            ["qyl.agent.diagnostic.phase"] = SemconvAttributeValueKind.String,
+            ["qyl.agent.diagnostic.probe.id"] = SemconvAttributeValueKind.String,
+            ["qyl.agent.diagnostic.snapshot.id"] = SemconvAttributeValueKind.String,
+            ["qyl.agent.diagnostic.variable.count"] = SemconvAttributeValueKind.Integer,
             ["qyl.capability.id"] = SemconvAttributeValueKind.String,
             ["qyl.capability.kind"] = SemconvAttributeValueKind.String,
             ["qyl.exception.source"] = SemconvAttributeValueKind.String,
@@ -806,6 +815,11 @@ internal static class SemconvRegistryFacts
             ["qyl.mcp.test_case.id"] = SemconvAttributeValueKind.String,
             ["qyl.mcp.tool.name"] = SemconvAttributeValueKind.String,
             ["qyl.project.id"] = SemconvAttributeValueKind.String,
+            ["qyl.workflow.agent.id"] = SemconvAttributeValueKind.String,
+            ["qyl.workflow.attempt.id"] = SemconvAttributeValueKind.String,
+            ["qyl.workflow.event.id"] = SemconvAttributeValueKind.String,
+            ["qyl.workflow.run.id"] = SemconvAttributeValueKind.String,
+            ["qyl.workflow.tool_call.id"] = SemconvAttributeValueKind.String,
             ["qyl.workspace.id"] = SemconvAttributeValueKind.String,
             ["rpc.connect_rpc.error_code"] = SemconvAttributeValueKind.String,
             ["rpc.grpc.status_code"] = SemconvAttributeValueKind.String,
@@ -1137,6 +1151,8 @@ private static readonly (string Prefix, SemconvAttributeValueKind Kind)[] Templa
             ["process.paging.fault_type"] = new[] { "major", "minor" },
             ["process.state"] = new[] { "defunct", "running", "sleeping", "stopped" },
             ["profile.frame.type"] = new[] { "beam", "cpython", "dotnet", "go", "jvm", "kernel", "luajit", "native", "perl", "php", "ruby", "rust", "v8js" },
+            ["qyl.agent.diagnostic.outcome"] = new[] { "fail", "not_evaluated", "pass", "unknown" },
+            ["qyl.agent.diagnostic.phase"] = new[] { "checkpoint", "error", "input", "output" },
             ["rpc.connect_rpc.error_code"] = new[] { "aborted", "already_exists", "cancelled", "data_loss", "deadline_exceeded", "failed_precondition", "internal", "invalid_argument", "not_found", "out_of_range", "permission_denied", "resource_exhausted", "unauthenticated", "unavailable", "unimplemented", "unknown" },
             ["rpc.grpc.status_code"] = new[] { "0", "1", "10", "11", "12", "13", "14", "15", "16", "2", "3", "4", "5", "6", "7", "8", "9" },
             ["rpc.message.type"] = new[] { "RECEIVED", "SENT" },
@@ -1190,7 +1206,7 @@ private static readonly (string Prefix, SemconvAttributeValueKind Kind)[] Templa
         new(new[] { "Qyl.Collector", "Qyl.Instrumentation.ErrorCapture", "Qyl.OpenTelemetry.AutoInstrumentation", "Qyl.OpenTelemetry.AutoInstrumentation.Database", "Qyl.OpenTelemetry.AutoInstrumentation.NServiceBus", "System.Runtime" }, StringComparer.Ordinal);
 
     private static readonly HashSet<string> KnownEventNames =
-        new(new[] { "app.crash", "app.jank", "app.screen.click", "app.widget.click", "az.resource.log", "azure.resource.log", "browser.web_vital", "db.client.operation.exception", "device.app.lifecycle", "exception", "faas.invocation.exception", "feature_flag.evaluation", "gen_ai.client.inference.operation.details", "gen_ai.client.operation.exception", "gen_ai.evaluation.result", "http.client.request.exception", "http.server.request.exception", "messaging.create.exception", "messaging.process.exception", "messaging.receive.exception", "messaging.send.exception", "messaging.settle.exception", "qyl.http.client", "qyl.rpc.grpc", "rpc.client.call.exception", "rpc.message", "rpc.server.call.exception", "session.end", "session.start" }, StringComparer.Ordinal);
+        new(new[] { "app.crash", "app.jank", "app.screen.click", "app.widget.click", "az.resource.log", "azure.resource.log", "browser.web_vital", "db.client.operation.exception", "device.app.lifecycle", "exception", "faas.invocation.exception", "feature_flag.evaluation", "gen_ai.client.inference.operation.details", "gen_ai.client.operation.exception", "gen_ai.evaluation.result", "http.client.request.exception", "http.server.request.exception", "messaging.create.exception", "messaging.process.exception", "messaging.receive.exception", "messaging.send.exception", "messaging.settle.exception", "qyl.agent.diagnostic.snapshot", "qyl.http.client", "qyl.rpc.grpc", "rpc.client.call.exception", "rpc.message", "rpc.server.call.exception", "session.end", "session.start" }, StringComparer.Ordinal);
 
     internal static readonly SemconvSpanRule[] SpanRules =
     {

src/Qyl.Telemetry.SemanticConventions.Incubating/Attributes/Qyl/QylAttributes.g.cs

@@ -13,6 +13,103 @@ namespace Qyl.Telemetry.SemanticConventions.Incubating.Attributes.Qyl;
 /// <summary>Qyl Attributes (incubating).</summary>
 public static class QylAttributes
 {
+    /// <summary>
+    /// Number of machine-readable checks in an agent diagnostic state frame.
+    /// </summary>
+    public const string AgentDiagnosticCheckCount = "qyl.agent.diagnostic.check.count";
+
+    /// <summary>
+    /// Number of failed checks in an agent diagnostic state frame.
+    /// </summary>
+    public const string AgentDiagnosticCheckFailedCount = "qyl.agent.diagnostic.check.failed_count";
+
+    /// <summary>
+    /// Stable discriminator of the machine-readable agent diagnostic extension.
+    /// </summary>
+    public const string AgentDiagnosticExtensionId = "qyl.agent.diagnostic.extension.id";
+
+    /// <summary>
+    /// Version of the machine-readable agent diagnostic state-frame format.
+    /// </summary>
+    public const string AgentDiagnosticFormatVersion = "qyl.agent.diagnostic.format.version";
+
+    /// <summary>
+    /// Deterministically computed aggregate outcome of an agent diagnostic state frame.
+    /// </summary>
+    public const string AgentDiagnosticOutcome = "qyl.agent.diagnostic.outcome";
+
+    /// <summary>
+    /// Values for the <c>AgentDiagnosticOutcome</c> attribute.
+    /// </summary>
+    public static class AgentDiagnosticOutcomeValues
+    {
+        /// <summary>
+        /// At least one evaluated diagnostic check failed.
+        /// </summary>
+        public const string Fail = "fail";
+
+        /// <summary>
+        /// The state frame contained no diagnostic checks.
+        /// </summary>
+        public const string NotEvaluated = "not_evaluated";
+
+        /// <summary>
+        /// Every evaluated diagnostic check passed.
+        /// </summary>
+        public const string Pass = "pass";
+
+        /// <summary>
+        /// No failed check was observed, but at least one check could not be evaluated.
+        /// </summary>
+        public const string Unknown = "unknown";
+    }
+
+    /// <summary>
+    /// Program boundary at which an agent diagnostic state frame was captured.
+    /// </summary>
+    public const string AgentDiagnosticPhase = "qyl.agent.diagnostic.phase";
+
+    /// <summary>
+    /// Values for the <c>AgentDiagnosticPhase</c> attribute.
+    /// </summary>
+    public static class AgentDiagnosticPhaseValues
+    {
+        /// <summary>
+        /// State captured at an explicit verification checkpoint.
+        /// </summary>
+        public const string Checkpoint = "checkpoint";
+
+        /// <summary>
+        /// State captured on an error path.
+        /// </summary>
+        public const string Error = "error";
+
+        /// <summary>
+        /// State captured before the probed operation.
+        /// </summary>
+        public const string Input = "input";
+
+        /// <summary>
+        /// State captured after the probed operation.
+        /// </summary>
+        public const string Output = "output";
+    }
+
+    /// <summary>
+    /// Bounded machine identifier of the diagnostic probe that captured the state frame.
+    /// </summary>
+    public const string AgentDiagnosticProbeId = "qyl.agent.diagnostic.probe.id";
+
+    /// <summary>
+    /// Stable identifier of one immutable agent diagnostic state frame.
+    /// </summary>
+    public const string AgentDiagnosticSnapshotId = "qyl.agent.diagnostic.snapshot.id";
+
+    /// <summary>
+    /// Number of dynamic variables described by an agent diagnostic state frame.
+    /// </summary>
+    public const string AgentDiagnosticVariableCount = "qyl.agent.diagnostic.variable.count";
+
     /// <summary>
     /// Stable identifier of the qyl capability that produced the telemetry.
     /// </summary>
@@ -78,6 +175,31 @@ public static class QylAttributes
     /// </summary>
     public const string ProjectId = "qyl.project.id";
 
+    /// <summary>
+    /// Stable workflow agent identifier mirrored into telemetry for journal correlation.
+    /// </summary>
+    public const string WorkflowAgentId = "qyl.workflow.agent.id";
+
+    /// <summary>
+    /// Stable workflow attempt identifier mirrored into telemetry for journal correlation.
+    /// </summary>
+    public const string WorkflowAttemptId = "qyl.workflow.attempt.id";
+
+    /// <summary>
+    /// Stable immutable workflow journal event identifier mirrored into telemetry for correlation.
+    /// </summary>
+    public const string WorkflowEventId = "qyl.workflow.event.id";
+
+    /// <summary>
+    /// Stable workflow run identifier mirrored into telemetry for journal correlation.
+    /// </summary>
+    public const string WorkflowRunId = "qyl.workflow.run.id";
+
+    /// <summary>
+    /// Stable workflow tool-call identifier mirrored into telemetry for journal correlation.
+    /// </summary>
+    public const string WorkflowToolCallId = "qyl.workflow.tool_call.id";
+
     /// <summary>
     /// qyl workspace identifier the telemetry belongs to.
     /// </summary>

src/Qyl.Telemetry.SemanticConventions.Incubating/Names/QylTelemetryNames.g.cs

@@ -55,17 +55,22 @@ public static class Scopes
     }
 
     /// <summary>
-    /// Names of the qyl-owned <c>DiagnosticSource</c> bridge events.
+    /// Names of qyl-owned <c>Activity</c> and <c>DiagnosticSource</c> events.
     /// </summary>
     public static class Events
     {
         /// <summary>
-        /// The <c>qyl.http.client</c> bridge event.
+        /// The <c>qyl.agent.diagnostic.snapshot</c> telemetry event.
+        /// </summary>
+        public const string QylAgentDiagnosticSnapshot = "qyl.agent.diagnostic.snapshot";
+
+        /// <summary>
+        /// The <c>qyl.http.client</c> telemetry event.
         /// </summary>
         public const string QylHttpClient = "qyl.http.client";
 
         /// <summary>
-        /// The <c>qyl.rpc.grpc</c> bridge event.
+        /// The <c>qyl.rpc.grpc</c> telemetry event.
         /// </summary>
         public const string QylRpcGrpc = "qyl.rpc.grpc";
     }