Qyl.Telemetry.SemanticConventions.SourceGeneration 4.3.0

Qyl.Telemetry.SemanticConventions.SourceGeneration

Roslyn source generator for OpenTelemetry semantic-convention constants, descriptors, and thin helper APIs. It does not collect telemetry. Consumers own their Meter, ActivitySource, Logger, instrumentation scope, versioning, and enablement.

When to use this package

This is the application-side consumption mode: the generator emits only the declared groups into your own assembly — internal visibility, no runtime package dependency, tree-shaken by construction. Libraries that need one pinned registry version across a package family (for example Qyl.OpenTelemetry.AutoInstrumentation) reference the compiled Qyl.Telemetry.SemanticConventions packages instead and alias their constants; see the repository README's "Choosing between the compiled packages and the source generator" section.

Use

using Qyl.Telemetry.SemanticConventions.SourceGeneration;

[SemanticConventionAttributes("http")]
internal static partial class HttpAttributes;

[SemanticConventionIncubatingAttributes("http")]
internal static partial class HttpIncubatingAttributes;

[SemanticConventionMetrics("http.server")]
internal static partial class HttpServerMetrics;

[SemanticConventionMeters("http.server")]
internal static partial class HttpServerMeters;

[SemanticConventionActivities("http")]
internal static partial class HttpActivityExtensions;

// Generated:
//   public const string AttributeHttpRequestMethod = "http.request.method";
//   public static partial class HttpServerRequestDurationDescriptor { ... }
//   public static Histogram<double> CreateHttpServerRequestDurationHistogram(this Meter meter)
//   public static Activity SetHttpRoute(this Activity activity, string value)

Generator surfaces

All four source generators use the same Roslyn shape: publish stable and incubating marker attributes during post-initialization, discover annotated partial classes with ForAttributeWithMetadataName, extract the requested semantic-convention prefix into a marker model, then emit source from the matching registry projection.

The marker attributes are themselves generated via RegisterPostInitializationOutput; no runtime dependency is added by consuming this package.

Stable markers emit stable rows plus deprecated migration symbols. Incubating markers are supersets: stable + development/alpha/beta/release-candidate + deprecated. This mirrors Java/Python's incubating package behavior and avoids breaking consumers when conventions are promoted.

Choose one projection per prefix in normal consumer code. Incubating is a superset, so declaring both stable and incubating meter/activity helpers for the same prefix in the same namespace can make shared extension methods ambiguous. If a test fixture intentionally declares both, call the generated static helper class explicitly.

Versioning

Tracks two source registries:

The generated provenance entries carry the exact resolved ref, commit, and schema URL; they are regenerated from the canonical pins instead of copied into this document.

The GenAI registry is development-stage. It is pinned by commit SHA and must not be presented as a stable v1.42.0 release.

The embedded registry is regenerated by scripts/generate.sh with the Weaver version pinned in Version.props; generation fails on a different binary. The script runs Weaver twice, once for core and once for GenAI, then merges the qyl-owned projections while preserving per-row source metadata. The core run excludes gen-ai, mcp, openai, and aws-bedrock, so those rows come only from the GenAI source.

The merge also fingerprints every effective model file, preserves both manifests, and embeds every referenced GenAI JSON Schema. Two generated consumers share that same projection:

• emit_registry_resources.py publishes the complete resolved registry and raw structured-payload schemas through the incubating package.
• emit_analyzer_registry.py derives attribute types, enum spellings, GenAI/MCP span requirements, provider refinements, and metric names for the analyzer project.

Both scripts support --check; normal repository builds and CI fail when their committed outputs drift from resolved-registry.json.

The generated member shape is snapshot-tested per stability tier on the repository's net10.0 test host. The release gate also restores the packed source generator into a clean net10.0 consumer, compiles generated members, and executes the result.

Licensed under Apache-2.0. Generated content is derived from the Apache-2.0 OpenTelemetry semantic-conventions registries.