[ANcpLua]

Aligns the docs to the canonical OpenTelemetry vocabulary and fixes a stale fact — the honest, repo-respecting version of "docs lead the implementation" (this repo's AGENTS.md prime directive is do not overstate / never synthesize, so no aspirational/unbuilt capability is added).

README

• New OpenTelemetry terminology section mapping the repo onto the official glossary: Instrumented Library (the 60-item contract surface), Instrumentation Library (this package family), Instrumentation Scope (QylActivitySource/QylActivityNames, name+version), Automatic Instrumentation (framed as the NativeAOT-safe form: compile-time [InterceptsLocation] interceptors + DiagnosticListener + [ModuleInitializer], explicitly not profiler/IL-rewrite), Semantic Conventions.
• States plainly that all three signals (traces/metrics/logs via ILogger/log4net/NLog) are contract-covered, and that AOT-structural items are marked unsupported_nativeaot, not hidden.
• Fixes the stale install example version 0.3.0-pre.1 → 3.1.2 (latest published).

CHANGELOG — synthetic Documentation entry per repo convention.

Scope guardrails honored: no <auto-generated/> blocks or docs/generated/*/contract/code touched (verified); the generated contract-summary block is byte-identical. Docs-only.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Added a new section clarifying OpenTelemetry terminology and how key concepts map to this project’s instrumentation approach.
  • Expanded guidance around automatic instrumentation with a NativeAOT-safe explanation.
  • Updated install examples to use the current 3.1.2 package versions.
  • Corrected a stale version reference in the changelog.

Walkthrough

README.md adds an "OpenTelemetry terminology" glossary section mapping OpenTelemetry concepts to repository terms, and updates install-example package version references to 3.1.2. CHANGELOG.md records both documentation changes under the "Documentation" heading.

Changes

Documentation Updates

Layer / File(s)	Summary
OpenTelemetry terminology section README.md	Adds a glossary table mapping OpenTelemetry terms (instrumented library, instrumentation library, scope, automatic instrumentation, semantic conventions) to repository implementation, including a NativeAOT-safe automatic instrumentation description.
Install example version fix and changelog README.md, CHANGELOG.md	Updates Qyl.OpenTelemetry.AutoInstrumentation.Hosting, .EntityFrameworkCore, and .SqlClient package reference examples to 3.1.2 (replacing stale 0.3.0-pre.1), and logs both README changes as Documentation bullets in CHANGELOG.md.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Docs-only diff, no code path, no diagram warranted. Version string corrected from 0.3.0-pre.1 to 3.1.2 — fine, it's what the README says now. Nothing else to check.

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the docs-only README glossary alignment and stale install-version fix.
Description check	✅ Passed	The description directly matches the README terminology update, version fix, and changelog entry.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/otel-terminology

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch claude/otel-terminology

---

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

Updates documentation to align repository terminology with the canonical OpenTelemetry glossary and refreshes the README install examples to a current released package version.

Changes:

• Added an “OpenTelemetry terminology” section to map glossary terms to this repository’s concepts and artifacts.
• Updated README NuGet PackageReference examples from 0.3.0-pre.1 to 3.1.2.
• Added a synthetic Documentation entry to the Unreleased section of the changelog.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
README.md	Adds glossary-aligned terminology mapping section and updates install snippet versions.
CHANGELOG.md	Records the documentation updates under an Unreleased “Documentation” section.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@README.md`:
- Around line 50-59: The README and changelog examples are hardcoding the wrong
package version; update the version strings in the documented package references
to match the repo’s current version. Change the
`Qyl.OpenTelemetry.AutoInstrumentation.Hosting`, `EntityFrameworkCore`, and
`SqlClient` references in the README snippet, and the matching version mention
in `CHANGELOG.md`, so they all use `3.0.2` instead of `3.1.2`.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 1210d6b9-00c7-4aa5-9fad-b5e4f831d921

📥 Commits

Reviewing files that changed from the base of the PR and between 5ceee81 and a8cbf3e.

📒 Files selected for processing (2)

• CHANGELOG.md
• README.md

📜 Review details

⏰ Context from checks skipped due to timeout. (2)

• GitHub Check: copilot-pull-request-reviewer
• GitHub Check: smoke (qyl-macos)

🧰 Additional context used

📓 Path-based instructions (1)

**

⚙️ CodeRabbit configuration file

AGENTS.md

**: # Qyl.OpenTelemetry.AutoInstrumentation agent rules

Mission

This repository is the runtime AOT auto-instrumentation lane for qyl, evolving into a
self-describing observability substrate. The foundation is unchanged: .NET 10
NativeAOT-compatible zero-code instrumentation through managed build assets, source generation,
DiagnosticListener consumption, and module-initializer boot. The direction is the North Star
below.

Keep this repository separate from:

• semantic-convention package generation (Qyl.OpenTelemetry.SemanticConventions is a referenced
  vocabulary package, not generated here),
• the old CLR-profiler/OpenTelemetry auto-instrumentation substrate.

North Star — declare and prove the whole stack

Every observability tool today is pull-by-observation: a backend learns what a service emits
by receiving samples over time, and never knows whether it has seen the whole surface. qyl has a
capability none of them have — because instrumentation is source-generated interceptors + a static
contract + a referenced semconv registry + (incrementally) DTO inference, the complete set of
telemetry a binary can ever produce is a compile-time-derivable fact, with provenance.

The substrate goal: every qyl binary ships a complete, machine-readable Telemetry Capability
Graph (TCG) — the full possible OpenTelemetry surface for that exact binary, each capability
tagged compile-time-owned vs runtime-valued — and proves it by self-hosting (instrumenting its
own pipeline with its own mechanism, zero extra code). Any external entity consumes the TCG to know
the entire stack before a span is sampled. The contract becomes the shared semantic graph; an OTLP
backend is just one consumer.

Three pillars:

1. Self-host (the proof). qyl instruments qyl with qyl — QylSelfTelemetry /
   SemConvConformanceProcessor are the seed; the binary observing itself is how "declared TCG ==
   runtime reality" is checked.
2. **Compile-time-complete ...

Files:

• CHANGELOG.md
• README.md

---

⚙️ CodeRabbit configuration file

**: Operating principles (solo-dev, agentic SDLC — reviews are advisory, agents act on them):

1. LAZY: one self-contained, correct review beats ten partial ones. Every finding is
   definitive — concrete evidence with file:line, a concrete fix, no "consider maybe",
   no open or ambiguous questions back to the author. If you cannot decide a point
   from the diff plus repo context, stay silent on it. Never cite a source, API, or
   version you have not verified; an unverifiable claim is a dropped claim.
2. IMPATIENT: never stall a PR. There are no compatibility obligations here — internal
   and dogfooding code has NO public-API contract; removing shims, breaking signatures,
   and deleting dead paths are normal, desirable changes. Do not flag backward
   compatibility, deprecation ceremony, or migration paths. (SemVer applies only to
   commercially sold libraries — this repo has none.)
3. EGO: hold the bar of the best reviewer on the market — flag real correctness,
   security, data-loss, and structural problems precisely; produce zero noise.

Files:

• CHANGELOG.md
• README.md

🔇 Additional comments (2)

CHANGELOG.md (1)

5-14: Same version mismatch as the README. This bullet repeats the 3.1.2 claim; once the install example is corrected, this note should be updated to 3.0.2 too.

README.md (1)

10-27: LGTM!

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n== Directory.Build.props ==\n'
if [ -f Directory.Build.props ]; then
  cat -n Directory.Build.props | sed -n '1,220p'
else
  echo "Directory.Build.props not found"
fi

printf '\n== README.md lines 40-80 ==\n'
cat -n README.md | sed -n '40,80p'

printf '\n== changelog/version mentions ==\n'
rg -n "3\.1\.2|3\.0\.2|PackageReference Include=\"Qyl\.OpenTelemetry\.AutoInstrumentation\.(Hosting|EntityFrameworkCore|SqlClient)\"" README.md CHANGELOG.md docs . -g '!**/bin/**' -g '!**/obj/**' || true

Repository: ANcpLua/Qyl.OpenTelemetry.AutoInstrumentation

Length of output: 10742

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo 'Directory.Build.props:'
if [ -f Directory.Build.props ]; then
  rg -n 'Version|PackageVersion|VersionPrefix' Directory.Build.props
else
  echo 'missing'
fi

echo
echo 'README.md:'
rg -n 'Qyl.OpenTelemetry.AutoInstrumentation\.(Hosting|EntityFrameworkCore|SqlClient)|3\.1\.2|3\.0\.2' README.md

echo
echo 'CHANGELOG.md:'
if [ -f CHANGELOG.md ]; then
  rg -n '3\.1\.2|3\.0\.2|Qyl.OpenTelemetry.AutoInstrumentation\.(Hosting|EntityFrameworkCore|SqlClient)' CHANGELOG.md
else
  echo 'missing'
fi

Repository: ANcpLua/Qyl.OpenTelemetry.AutoInstrumentation

Length of output: 1252

---

Update the package version in the docs. README.md:50-59 and CHANGELOG.md:13 still hardcode 3.1.2, but the repo version is 3.0.2 in Directory.Build.props. Switch both snippets to 3.0.2.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` around lines 50 - 59, The README and changelog examples are
hardcoding the wrong package version; update the version strings in the
documented package references to match the repo’s current version. Change the
`Qyl.OpenTelemetry.AutoInstrumentation.Hosting`, `EntityFrameworkCore`, and
`SqlClient` references in the README snippet, and the matching version mention
in `CHANGELOG.md`, so they all use `3.0.2` instead of `3.1.2`.