Skip to content
This repository was archived by the owner on May 25, 2026. It is now read-only.
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ When published, consume it as a development-only analyzer dependency:
<PackageReference Include="Qyl.OpenTelemetry.SemanticConventions.Analyzers"
Version="..."
PrivateAssets="all"
IncludeAssets="runtime; build; native; contentfiles; analyzers; buildtransitive" />
IncludeAssets="analyzers; buildtransitive" />
```

For local evaluation from this checkout, reference the analyzer project directly from a consumer project:
Expand All @@ -40,8 +40,8 @@ The package-level generated catalog is in [`docs/Qyl.OpenTelemetry.SemanticConve
| [`QYL0014`](docs/Qyl.OpenTelemetry.SemanticConventions.Analyzers.md#qyl0014) | Warning | Yes | Hard-coded value matches a semantic-convention value constant marked `[Obsolete]` |
| [`QYL0021`](docs/Qyl.OpenTelemetry.SemanticConventions.Analyzers.md#qyl0021) | Warning | No | Library directly references incubating semantic-convention members |
| [`QYL0030`](docs/Qyl.OpenTelemetry.SemanticConventions.Analyzers.md#qyl0030) | Error | Exact replacements only | Supplemental catalog exact replacement in production telemetry emission |
| [`QYL0031`](docs/Qyl.OpenTelemetry.SemanticConventions.Analyzers.md#qyl0031) | Warning | Exact replacements only | Supplemental catalog context-sensitive, manual-review, removed/no-replacement, or ambiguous payload migration |
| [`QYL0032`](docs/Qyl.OpenTelemetry.SemanticConventions.Analyzers.md#qyl0032) | Info | Exact replacements only | Supplemental catalog item appears in test, fixture, compatibility, generated, translator, or catalog context |
| [`QYL0031`](docs/Qyl.OpenTelemetry.SemanticConventions.Analyzers.md#qyl0031) | Warning | No | Supplemental catalog context-sensitive, manual-review, removed/no-replacement, or ambiguous payload migration |
| [`QYL0032`](docs/Qyl.OpenTelemetry.SemanticConventions.Analyzers.md#qyl0032) | Info | No | Supplemental catalog item appears in test, fixture, compatibility, generated, translator, or catalog context |

## Examples

Expand All @@ -64,7 +64,7 @@ activity.SetTag("error.message", message); // QYL0031; replacem
- **Multi-hop rename resolution.** `SemconvMigrationCatalog.ResolveTerminalReplacement` chases `ExactRename` chains (e.g. `http.host` → `net.host.name` → `server.address`) so code-fixes land consumers on the terminal symbol, not on a still-deprecated mid-state. Cycles and chains over 8 hops bail at the last safe step.
- **Structured changelog provenance.** Every `SemconvMigrationCatalogEntry` may carry an optional `SemconvChangelogEvidence` (commit / version / url / quote) pinning the migration claim to an exact upstream commit, so the catalog is auditable without re-parsing CHANGELOG.md.
- **Catalog seeding from upstream.** `scripts/seed-catalog.sh <from-tag> <to-tag>` clones a shallow upstream `open-telemetry/semantic-conventions` checkout, slices CHANGELOG.md between two version tags, and emits C# (or `--format json`) skeleton entries with provenance pre-filled. Curate the `Kind`/`Domain`/`Signal`/`MigrationKind` fields by hand before merging.
- **Generated docs and audit.** Regenerate the package catalog with `scripts/generate-docs.sh generate`; validate with `scripts/generate-docs.sh validate`; print the current 156-entry coverage audit with `scripts/generate-docs.sh audit`. Every `QYL*` rule has a stable `#qyl0010` anchor in the generated docs that every `DiagnosticDescriptor.HelpLinkUri` resolves to.
- **Generated docs and audit.** Regenerate the package catalog with `scripts/generate-docs.sh generate`; validate with `scripts/generate-docs.sh validate`; print the current coverage audit with `scripts/generate-docs.sh audit`. Every `QYL*` rule has a stable `#qyl0010` anchor in the generated docs that every `DiagnosticDescriptor.HelpLinkUri` resolves to.
- **netstandard2.0** only — required by Roslyn analyzer host. Microsoft.CodeAnalysis.* dependencies only.
- **Multi-version friendly.** A consumer on SemConv 1.39.0 gets live metadata diagnostics scoped to the 1.39.0 surface; upgrading expands those diagnostics automatically. The supplemental catalog is a conservative v1.41.0 migration aid.

Expand Down Expand Up @@ -135,7 +135,7 @@ tests/WeaverRoundTrip/generate.sh
# 4. Confirm the analyzer fires QYL0010 against the regenerated file:
dotnet build Qyl.OpenTelemetry.SemanticConventions.Analyzers.slnx \
-c Release -warnaserror:QYL0010
dotnet test tests/Qyl.OpenTelemetry.SemanticConventions.Analyzers.Tests/Qyl.OpenTelemetry.SemanticConventions.Analyzers.Tests.csproj \
dotnet test tests/ANcpLua.OpenTelemetry.SemanticConventions.Analyzers.Tests/ANcpLua.OpenTelemetry.SemanticConventions.Analyzers.Tests.csproj \
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 HIGH RISK

The project path should use the Qyl prefix to match the repository structure and the package ID defined elsewhere in this file.

Suggested change
dotnet test tests/ANcpLua.OpenTelemetry.SemanticConventions.Analyzers.Tests/ANcpLua.OpenTelemetry.SemanticConventions.Analyzers.Tests.csproj \
dotnet test tests/Qyl.OpenTelemetry.SemanticConventions.Analyzers.Tests/Qyl.OpenTelemetry.SemanticConventions.Analyzers.Tests.csproj \

--filter 'FullyQualifiedName~WeaverRoundTrip'
```

Expand All @@ -147,15 +147,15 @@ Run the repository gates before changing diagnostics, catalog data, or generated

```bash
dotnet build Qyl.OpenTelemetry.SemanticConventions.Analyzers.slnx -c Release
dotnet test tests/Qyl.OpenTelemetry.SemanticConventions.Analyzers.Tests/Qyl.OpenTelemetry.SemanticConventions.Analyzers.Tests.csproj
dotnet test tests/ANcpLua.OpenTelemetry.SemanticConventions.Analyzers.Tests/ANcpLua.OpenTelemetry.SemanticConventions.Analyzers.Tests.csproj
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 HIGH RISK

The project path should use the Qyl prefix.

Suggested change
dotnet test tests/ANcpLua.OpenTelemetry.SemanticConventions.Analyzers.Tests/ANcpLua.OpenTelemetry.SemanticConventions.Analyzers.Tests.csproj
dotnet test tests/Qyl.OpenTelemetry.SemanticConventions.Analyzers.Tests/Qyl.OpenTelemetry.SemanticConventions.Analyzers.Tests.csproj

scripts/generate-docs.sh validate
scripts/generate-docs.sh audit
git diff --check
```

## Incubation

This repository is the incubation home for what may eventually be proposed as an official `OpenTelemetry.SemanticConventions.Analyzers` companion to `opentelemetry-dotnet-contrib`. While here, it ships under the `ANcpLua.*` package ID and Apache-2.0 license.
This repository is the incubation home for what may eventually be proposed as an official `OpenTelemetry.SemanticConventions.Analyzers` companion to `opentelemetry-dotnet-contrib`. While here, it ships under the `Qyl.*` package ID and Apache-2.0 license.

## License

Expand Down
14 changes: 7 additions & 7 deletions docs/Qyl.OpenTelemetry.SemanticConventions.Analyzers.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Qyl.OpenTelemetry.SemanticConventions.Analyzers

<!-- <auto-generated /> This file is generated by tools/Qyl.OpenTelemetry.SemanticConventions.Analyzers.DocsGenerator. -->
<!-- <auto-generated /> This file is generated by tools/ANcpLua.OpenTelemetry.SemanticConventions.Analyzers.DocsGenerator. -->
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 HIGH RISK

The tool name should remain consistent with the Qyl prefix used throughout the project.

Suggested change
<!-- <auto-generated /> This file is generated by tools/ANcpLua.OpenTelemetry.SemanticConventions.Analyzers.DocsGenerator. -->
<!-- <auto-generated /> This file is generated by tools/Qyl.OpenTelemetry.SemanticConventions.Analyzers.DocsGenerator. -->


This package analyzes OpenTelemetry semantic-convention usage in C# consumers. The consumer's referenced `OpenTelemetry.SemanticConventions` assembly remains the primary source of truth: rules that read `[Obsolete]` metadata report what that package actually generated. The curated inventory below separates live-metadata coverage from supplemental diagnostics for changelog/model entries that are not reliably visible through live metadata.

Expand All @@ -17,8 +17,8 @@ This package analyzes OpenTelemetry semantic-convention usage in C# consumers. T
| QYL0014 | Warning | Deprecated semantic-convention value | Yes | A constant string used as the value of a known semantic-convention telemetry attribute matches a value member that is marked [Obsolete] in the consumer's referenced *Values enum class. |
| QYL0021 | Warning | Incubating semantic-convention member used in a library | No | Members under any *.SemanticConventions.Incubating namespace may rename or change values across minor package releases. Library projects (non-exe, non-test) baking direct references push that volatility onto every downstream consumer. |
| QYL0030 | Error | Obsolete semantic convention has an exact replacement | Exact replacements only | A hard-coded semantic-convention name or value matches the supplemental OpenTelemetry migration catalog and has a one-to-one replacement. This supplements, but does not replace, [Obsolete] metadata from OpenTelemetry.SemanticConventions. |
| QYL0031 | Warning | Semantic convention migration needs review | Exact replacements only | A hard-coded semantic-convention name or value matches the supplemental OpenTelemetry migration catalog, but the migration is context-sensitive or has no safe automatic replacement. |
| QYL0032 | Info | Legacy semantic convention appears in compatibility or test code | Exact replacements only | A hard-coded semantic-convention name or value appears in test, fixture, compatibility, translator, generated, or catalog code. Keep it only when the old schema is intentionally modeled. |
| QYL0031 | Warning | Semantic convention migration needs review | No | A hard-coded semantic-convention name or value matches the supplemental OpenTelemetry migration catalog, but the migration is context-sensitive or has no safe automatic replacement. |
| QYL0032 | Info | Legacy semantic convention appears in compatibility or test code | No | A hard-coded semantic-convention name or value appears in test, fixture, compatibility, translator, generated, or catalog code. Keep it only when the old schema is intentionally modeled. |
Comment on lines +20 to +21
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Mark QYL0031/QYL0032 as fixable in generated docs

These rows now say Code fix = No, but the codebase still exposes fixes for both IDs: SupplementalSemconvMigrationCodeFixProvider includes QYL0031 and QYL0032 in FixableDiagnosticIds and registers replacements for exact-rename/value-rename cases (src/ANcpLua.OpenTelemetry.SemanticConventions.Analyzers/SupplementalSemconvMigrationCodeFixProvider.cs, lines 9-14 and 55-66). Because exact-replacement catalog entries can be downgraded to QYL0031/QYL0032 by context, documenting them as non-fixable is incorrect and will drift from the docs generator output.

Useful? React with 👍 / 👎.


## Rule Reference

Expand Down Expand Up @@ -102,15 +102,15 @@ Code fix: Exact replacements only.

A hard-coded semantic-convention name or value matches the supplemental OpenTelemetry migration catalog, but the migration is context-sensitive or has no safe automatic replacement.

Code fix: Exact replacements only.
Code fix: No.

### QYL0032

**Legacy semantic convention appears in compatibility or test code** — *Info, category `OpenTelemetry.SemanticConventions`*

A hard-coded semantic-convention name or value appears in test, fixture, compatibility, translator, generated, or catalog code. Keep it only when the old schema is intentionally modeled.

Code fix: Exact replacements only.
Code fix: No.


## Precedence and Suppression
Expand Down Expand Up @@ -458,8 +458,8 @@ These value rows are intentionally separate from the 156-entry name/key/event/me
Regenerate with:

```bash
dotnet run -c Release --project tools/Qyl.OpenTelemetry.SemanticConventions.Analyzers.DocsGenerator
dotnet run -c Release --project tools/Qyl.OpenTelemetry.SemanticConventions.Analyzers.DocsGenerator -- --check
dotnet run -c Release --project tools/ANcpLua.OpenTelemetry.SemanticConventions.Analyzers.DocsGenerator
dotnet run -c Release --project tools/ANcpLua.OpenTelemetry.SemanticConventions.Analyzers.DocsGenerator -- --check
Comment on lines +461 to +462
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 HIGH RISK

The tool project path must use the Qyl prefix to match the repository structure.

Suggested change
dotnet run -c Release --project tools/ANcpLua.OpenTelemetry.SemanticConventions.Analyzers.DocsGenerator
dotnet run -c Release --project tools/ANcpLua.OpenTelemetry.SemanticConventions.Analyzers.DocsGenerator -- --check
dotnet run -c Release --project tools/Qyl.OpenTelemetry.SemanticConventions.Analyzers.DocsGenerator
dotnet run -c Release --project tools/Qyl.OpenTelemetry.SemanticConventions.Analyzers.DocsGenerator -- --check

```

The `--check` mode fails if the generated markdown differs from the checked-in file.
Loading