Qyl.OpenTelemetry.AutoInstrumentation 3.0.2

Qyl.OpenTelemetry.AutoInstrumentation

A .NET 10, NativeAOT-ready, vendor-neutral auto-instrumentation library.

The current product is pure managed code. It uses Roslyn source generators, DiagnosticListener, ActivitySource, Meter, build-transitive package assets, and [ModuleInitializer] bootstrapping. It does not use a CLR profiler, startup hook, runtime IL rewrite, attach tool, plugin store, or reflection-based dispatch.

What this repository ships

The repository also contains real consumer demos, source-generator snapshots, NativeAOT smoke consumers, OTLP-shaped fixtures, and package-layout checks. These are not decorative; they are the product proof surface.

Install shape

Use package references. A normal app should not call qyl boot APIs just to get baseline instrumentation.

<ItemGroup>
  <PackageReference Include="Qyl.OpenTelemetry.AutoInstrumentation.Hosting" Version="0.3.0-pre.1" />
</ItemGroup>

Add package-specific references only when the app uses those libraries:

<ItemGroup>
  <PackageReference Include="Qyl.OpenTelemetry.AutoInstrumentation.EntityFrameworkCore" Version="0.3.0-pre.1" />
  <PackageReference Include="Qyl.OpenTelemetry.AutoInstrumentation.SqlClient" Version="0.3.0-pre.1" />
</ItemGroup>

PackageReference is the supported zero-code path because NuGet carries the analyzer, build/, and buildTransitive/ assets into the consuming compilation. A bare runtime ProjectReference is not equivalent: MSBuild does not automatically flow analyzer and build assets from a referenced project. The verified dogfooding path explicitly references the runtime project, the generator project as an analyzer, and the core targets file.

How bootstrapping works

1. Build assets enable the interceptor namespace (InterceptorsNamespaces) in the consumer compilation.
2. The source generator discovers supported source-visible call-sites, emits ordinary C# interceptors annotated with [InterceptsLocation], and emits the file-local InterceptsLocationAttribute definition into the same generated file.
3. Package bootstrap code runs through [ModuleInitializer] and activates qyl once per process.
4. Runtime listeners consume values supplied by framework/library events or current activities. Missing values stay missing.
5. Emitted telemetry uses stable OpenTelemetry attributes by default. Query-string values in url.full/url.query are redacted to Redacted (keys stay); raw query values and db.query.text are upstream-flag opt-ins.

Supported proof surface

Runtime rules

• Do not invent runtime values. If the instrumented library did not expose a value, qyl does not synthesize it from guesses.
• Do not put full URLs, request paths, query strings, IDs, exception messages, or arbitrary caller text in span names.
• Prefer bounded attributes: route templates over raw paths, database operation/summary over raw statements, well-known error identifiers over exception messages.
• Consume deprecated OpenTelemetry aliases as inputs only; do not re-emit them as canonical output.
• Keep metric instruments and activity sources process-level, not per request.
• Keep conformance/self-telemetry opt-in when it adds per-span work.

Configuration

QylAutoInstrumentationOptions reads the 60-item OpenTelemetry .NET auto-instrumentation contract resolved from docs/contracts/otel-dotnet-auto-60.upstream.yaml plus docs/contracts/qyl-aot-ownership.yaml. Contract coverage is reported in docs/coverage-matrix.md.

Query values are redacted by default; the upstream flags switch redacted to raw:

OTEL_DOTNET_EXPERIMENTAL_HTTPCLIENT_DISABLE_URL_QUERY_REDACTION=true
OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_DISABLE_URL_QUERY_REDACTION=true

Custom metric meters can be appended to the source-generated meter registration path with the upstream additional-sources option. Names are case-sensitive and de-duplicated:

OTEL_DOTNET_AUTO_METRICS_ADDITIONAL_SOURCES=YourCompany.CustomMeter,Other.Meter

The conformance processor is off by default:

QYL_CONFORMANCE_ENABLED=1

Generated contract ownership summary

The upstream OpenTelemetry contract, qyl mechanism ownership, and generated resolved contract are split deliberately:

Verification

The broad handoff gate is:

python3 tools/verify-aot-autoinstrumentation-goal.py

Important focused gates:

python3 tools/verify-package-layout.py
python3 tools/verify-projectreference-behavior.py
python3 tools/verify-source-interceptor-consumer.py
python3 tools/verify-nativeaot-consumer.py
python3 tools/verify-otlp-fixtures.py
python3 tools/verify-otlp-collector-fixtures.py
python3 tools/verify-webapi-aot-demo.py
bash tools/smoketest.sh

Benchmark measurements live in benchmarks/Qyl.OpenTelemetry.AutoInstrumentation.Benchmarks. They are measurement evidence, not product code.

NativeAOT boundaries

• The source generator targets netstandard2.0 because it runs inside the compiler. It is excluded from NativeAOT publish graphs; consumers receive its analyzer output at build time.
• EFCore NativeAOT requires a compiled model. The compiled model in the demo is generated by EF tooling and may contain System.Reflection; that is not qyl runtime dispatch.
• Microsoft.Data.SqlClient currently emits its own trim/AOT warnings and does not support invariant globalization. qyl keeps this boundary explicit instead of hiding it in Hosting.
• Classic ASP.NET and WCF dynamic parity items from the upstream contract are explicitly unsupported for this NativeAOT/source-generator substrate.

Current limitations and next work

• Finish a full OTLP export normalizer instead of only OTLP-shaped committed fixtures.
• Add automated update flow for the 60-item contract manifest and generated coverage matrix.
• Expand source-generator target coverage only where call-sites are source-visible and stable.
• Add benchmark budget gates once the measurement noise floor is stable across CI runners.
• Improve user experience around package selection, ProjectReference dogfooding, and failure messages when build assets are missing.

See CHANGELOG.md for the synthesized five-commit history and continuation plan.