From a8cbf3e97a4b2b164fd271bc17174dfb607b0fc5 Mon Sep 17 00:00:00 2001 From: ancplua Date: Wed, 1 Jul 2026 07:40:11 +0200 Subject: [PATCH] docs: pin README to the OpenTelemetry glossary; fix stale install version Map the repo onto the official OTel terms (Instrumented Library / Instrumentation Library / Instrumentation Scope / Automatic Instrumentation / Semantic Conventions), framing the AOT source-interceptor + DiagnosticListener mechanism as OTel Automatic Instrumentation. Note all three signals (traces/metrics/logs) are contract-covered and AOT-structural gaps are marked, not hidden. Correct the install example version 0.3.0-pre.1 -> 3.1.2 (latest published). Co-Authored-By: Claude Opus 4.8 --- CHANGELOG.md | 10 ++++++++++ README.md | 24 +++++++++++++++++++++--- 2 files changed, 31 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c49c8cb4..0bceb108 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,16 @@ ## Unreleased +### Documentation + +- README: pinned the vocabulary to the official OpenTelemetry glossary (Instrumented Library / + Instrumentation Library / Instrumentation Scope / Automatic Instrumentation / Semantic + Conventions) and mapped each term onto this repository, framing the AOT source-interceptor + + `DiagnosticListener` mechanism as OpenTelemetry "Automatic Instrumentation". Stated that all + three signals (traces, metrics, logs) are contract-covered and that AOT-structural items are + marked `unsupported_nativeaot`, not hidden. +- README: corrected the stale install-example package version (`0.3.0-pre.1` -> `3.1.2`). + ### Telemetry semantics - Expanded the metrics registration surface with the useful part of the superseded diff --git a/README.md b/README.md index abc6a25f..ae46fe48 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,24 @@ The current product is pure managed code. It uses Roslyn source generators, `[ModuleInitializer]` bootstrapping. It does not use a CLR profiler, startup hook, runtime IL rewrite, attach tool, plugin store, or reflection-based dispatch. +## OpenTelemetry terminology + +This repository maps precisely onto the [OpenTelemetry glossary](https://opentelemetry.io/docs/concepts/glossary/): + +| OpenTelemetry term | Definition | In this repository | +|---|---|---| +| **Instrumented Library** | The library for which telemetry (traces, metrics, logs) is gathered. | The libraries in the 60-item contract: HttpClient, ASP.NET Core, EF Core, `Microsoft.Data.SqlClient`, `Grpc.Net.Client`, Confluent.Kafka, RabbitMQ.Client, MongoDB.Driver, StackExchange.Redis, Quartz, MassTransit, NServiceBus, MySqlConnector/MySql.Data, Npgsql, SQLite, Oracle MDA, Elasticsearch, GraphQL, Azure SDK. See [`docs/coverage-matrix.md`](docs/coverage-matrix.md). | +| **Instrumentation Library** *(a.k.a. Instrumenting Library)* | The library that provides instrumentation for an Instrumented Library. | **This package family** — `Qyl.OpenTelemetry.AutoInstrumentation` (+ `.Hosting`/`.EntityFrameworkCore`/`.SqlClient`). It emits the OpenTelemetry API calls on the Instrumented Libraries' behalf. | +| **Instrumentation Scope** | The `name` (+ optional `version`) given when obtaining a Tracer / Meter / Logger; identifies the scope emitting telemetry. | The `ActivitySource` / `Meter` names carried by the generated semantic registry (`QylActivitySource` / `QylActivityNames`), qualified with the package version. | +| **Automatic Instrumentation** | Telemetry collection that does **not** require modifying application source code (via compile-time/runtime code manipulation, monkey-patching, or eBPF). | qyl's method is the **NativeAOT-safe** form: build-time Roslyn `[InterceptsLocation]` source interceptors + `DiagnosticListener` consumption + `[ModuleInitializer]` bootstrap — zero app-code changes via `PackageReference`. Explicitly **not** a CLR profiler, IL rewrite, startup hook, or reflection dispatch (those are not AOT-compatible). | +| **Semantic Conventions** | The shared attribute/metric/span vocabulary telemetry follows. | Emitted against the referenced `Qyl.OpenTelemetry.SemanticConventions` package (a *vocabulary* dependency, not generated here). | + +All three OpenTelemetry signals are covered by the contract: **traces**, **metrics**, and +**logs** (`ILogger`, log4net, NLog). Per-item lane, status, call-site visibility, and evidence +are tracked in the generated coverage matrix; items that are structurally impossible under the +NativeAOT / source-generator substrate (classic ASP.NET, WCF, ASP.NET metrics — all +reflection-required) are marked `unsupported_nativeaot` rather than hidden. + ## What this repository ships | Package project | Purpose | @@ -29,7 +47,7 @@ instrumentation. ```xml - + ``` @@ -37,8 +55,8 @@ Add package-specific references only when the app uses those libraries: ```xml - - + + ```