OtelGenLint

A CLI linter and GitHub Action that validates every gen_ai.* attribute in your codebase against the OpenTelemetry GenAI semantic conventions, catching typos, stale names, and missing opt-in configuration before they silently break your LLM observability.

Problem

Teams building AI applications are adding OpenTelemetry GenAI instrumentation today — but the spec is in "Development" status, each provider SDK (Anthropic, OpenAI, Bedrock) instruments slightly differently, and there is no tooling to validate that attribute names, required opt-in environment variables, or span structure are correct. A backend engineer who writes gen_ai.provider.model instead of gen_ai.request.model, or who ships without OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental, gets telemetry that drops silently — only discovered when a cost-attribution dashboard is empty or a latency alert never fires. The June 2026 ecosystem survey found this "ships blind" pattern is the single most common failure mode in teams adopting the GenAI conventions.

Target user

Backend and platform engineers at AI-first startups and mid-market enterprises who own the observability stack. They are already running Datadog, Elastic, or Grafana with OTel, are actively adding gen_ai.* spans for LLM cost attribution and latency tracking, and trust linters for code style but have no equivalent for telemetry correctness. They need a CI gate, not a dashboard — the bug should fail the PR, not show up in production metrics two weeks later.

MVP scope

• otel-gen-lint scan <path> recursively scans TypeScript and Python source files for gen_ai.* string literals, validates each attribute name against a bundled snapshot of the OpenTelemetry GenAI spec JSON, and reports unknown or deprecated names with the correct replacement.
• A local spec cache at ~/.cache/otel-gen-lint/semconv.json storing versioned snapshots; otel-gen-lint update fetches the latest experimental release from the OTel GitHub.
• Checks for OTEL_SEMCONV_STABILITY_OPT_IN in source files, .env templates, and Dockerfiles — warns when gen_ai_latest_experimental attributes are used but the opt-in is absent.
• GitHub Action (uses: otel-gen-lint/action@v1) that runs on pull requests, posts inline annotations on changed lines introducing spec violations, and exits non-zero so the check is blockable.
• --output sarif flag for uploading results to GitHub Code Scanning (zero extra config for teams already using SARIF).
• Distributed as a Docker image, npx otel-gen-lint, and pip install otel-gen-lint.

Monetization

Freemium. Core CLI and GitHub Action are MIT-licensed and free forever — that is the adoption wedge. OtelGenLint Pro at $8/seat/month adds: a hosted spec-mirror service that tracks every OpenTelemetry experimental semconv release and pushes a Slack/email diff the day a gen_ai.* attribute name changes; a team dashboard showing which repos carry stale attribute names; and priority support for Go, Java, and Rust language plugins. Target buyer is the platform/SRE team at a 50–500 person AI-heavy company paying $5k–$20k/year in LLM observability tooling where a broken span means a missing cost center.

Why now

The OpenTelemetry GenAI semantic conventions sit at an uncomfortable inflection point: officially in "Development" status with no public stabilization timeline as of June 2026, yet "widely adopted across modern enterprise projects" (Datadog v1.37+, Elastic). Teams are instrumenting production workloads against a moving target with no guard rails. A May 2026 Greptime deep-dive documented the full six-layer spec — client spans, agent spans, MCP conventions, events, metrics, provider-specific attributes — and found that the transition environment variable (OTEL_SEMCONV_STABILITY_OPT_IN) is the single most-overlooked configuration element. A June 2026 analysis of real enterprise deployments confirmed that broken span hierarchies caused by attribute name mismatches are "the single greatest technical failure mode" in GenAI observability rollouts. Elastic's 2026 Observability Trends report names OTel GenAI as one of two forces reshaping enterprise observability this year — but no linting layer exists to validate developer implementations before they ship.

Risks & open questions

• Demand-side: platform engineers may assume their OTel SDK auto-validates attribute names (it does not) and only discover the problem is real after the first painful dashboard outage; the positioning must make this pain immediate and concrete, not hypothetical.
• Build-side: the OTel GenAI spec is published as Markdown pages, not a machine-readable attribute registry — extracting a canonical list of valid gen_ai.* names requires either a scraper against the spec repo or manual curation of ~60–80 attributes; the scraper approach needs to track upstream repo changes.
• Spec churn: if OTel moves quickly from experimental to stable and renames several attributes in the process, the linter's warning set will need a fast-follower update cycle — this is actually a Pro-tier retention argument, not just a risk.
• Coverage ceiling: only Python and TypeScript in v1 leaves Go and Java teams (a large fraction of enterprise backend) unserved; community PRs will be necessary to scale language support.
• Competitive displacement: if Anthropic, OpenAI, or a major OTel instrumentation library ships attribute validation natively, the standalone linter loses its wedge — durable value then lives in the CI gate, SARIF output, and the spec-update notification service.

Next step

Promote to weekly prototype — build the Python CLI that extracts attribute names from the OTel spec repo Markdown, validates them against a test corpus of real instrumentation code, and ships the GitHub Action YAML. Dogfood on this repo's own AI agent session tooling.

Sources

• https://greptime.com/blogs/2026-05-09-opentelemetry-genai-semantic-conventions — May 9, 2026 deep-dive on the six-layer OTel GenAI spec, adoption by Datadog and Elastic, and the OTEL_SEMCONV_STABILITY_OPT_IN transition story
• https://agileleadershipdayindia.org/blogs/ai-agent-observability-opentelemetry/opentelemetry-genai-semantic-conventions-explained.html — June 2026 analysis identifying "ships blind without opt-in" as the most common GenAI observability failure, with the broken span hierarchy pattern
• https://opentelemetry.io/docs/specs/semconv/gen-ai/ — official OTel GenAI semantic conventions spec (Development status), the source-of-truth for attribute names the linter validates against