phy-otel-audit — OpenTelemetry Instrumentation Auditor#

Scans your source code for 10 classes of missing or misconfigured OpenTelemetry instrumentation that cause invisible blind spots in your traces: unspanned HTTP handlers, DB calls outside trace context, swallowed span errors, missing service.name attributes, and more.

Quick Start#

bash

# Scan a directory
python otel_audit.py ./src

# Single file
python otel_audit.py src/handlers/users.js

# CI mode — exit 1 on HIGH findings
python otel_audit.py ./src --ci

# Verbose: show which line triggered each finding
python otel_audit.py ./src --verbose

# Only HIGH findings
python otel_audit.py ./src --only-severity HIGH

The 10 Checks#

IDSeverityCheckOT001HIGHNo OTel SDK imported anywhere — zero instrumentationOT002HIGHHTTP handler without span creationOT003HIGHDatabase/cache call outside active spanOT004HIGHException caught but span.recordException() not calledOT005MEDIUMservice.name not set in Resource attributesOT006MEDIUMOTel SDK initialized after first import (instrumentation gap)OT007MEDIUMSpan created but status not set on error pathOT008MEDIUMAsync context propagation missing (Promise/goroutine context not passed)OT009LOWTrace exporter using console/stdout in non-dev environmentOT010LOWManual span naming uses dynamic values (high-cardinality span names)

OT001 — No OTel SDK Imported#

Scans all files for any OpenTelemetry import. If none found, zero instrumentation exists.

Detected imports:

• JS/TS: @opentelemetry/api, @opentelemetry/sdk-node, @opentelemetry/auto-instrumentations-node
• Python: opentelemetry, opentelemetry-sdk, from opentelemetry
• Go: go.opentelemetry.io/otel
• Java: io.opentelemetry, opentelemetry-java

OT002 — HTTP Handler Without Span#

Finds route handler definitions (Express, FastAPI, Flask, gin, Spring) without a tracer.startSpan or tracer.startActiveSpan nearby. Auto-instrumentation covers framework-level spans, but business logic within handlers needs custom spans for meaningful traces.

OT003 — Database/Cache Call Outside Span#

Detects DB/cache operations ( db.query, prisma., mongoose., cursor.execute, db.Execute, redis.get, cache.get) that appear in functions where no span context is active (no tracer.startActiveSpan, no ctx parameter carrying trace context, no with tracer.start_as_current_span).

OT004 — Exception Not Recorded on Span#

Finds catch blocks or except clauses that handle errors but don't call span.recordException(err) and span.setStatus({ code: SpanStatusCode.ERROR }). Unrecorded exceptions make traces appear successful when they failed — the most common OTel mistake.

OT005 — Missing service.name Resource#

Scans OTel SDK initialization code for Resource.create or resource: config without service.name. Without service.name, all traces appear as unknown_service in backends (Jaeger/Tempo/Honeycomb) — impossible to filter.

OT006 — SDK Initialized After First Import#

In Node.js, require('@opentelemetry/sdk-node') must happen before any other require statements. If SDK init file is imported after other modules, auto-instrumentation patches miss the already-loaded modules. Detects tracing.js or instrumentation.js imported after other modules in entry files.

OT007 — Span Status Not Set on Error Path#

Finds span.end() calls in error branches (catch blocks, error handlers) without a preceding span.setStatus(SpanStatusCode.ERROR) or span.setStatus({ code: 2 }). Span ends without status = treated as OK by the backend.

OT008 — Context Not Propagated Through Async#

Finds Promise.all(, asyncio.gather(, or goroutine go func() patterns where the OTel context is not explicitly passed. In Go, context.Context must be threaded through goroutines manually. In Python asyncio, OpenTelemetry context is propagated automatically via contextvars — but only if tasks are created from within an active span.

OT009 — Console/Stdout Exporter in Production#

Finds ConsoleSpanExporter, SimpleSpanProcessor(new ConsoleSpanExporter()), or ConsoleMetricExporter outside of dev/test configuration files. Console exporters flood logs and provide no tracing backend value in production.

OT010 — High-Cardinality Span Names#

Finds tracer.startSpan( with dynamic values in the span name (string interpolation with variables, request paths with IDs). High-cardinality span names ( GET /users/12345) break trace aggregation — span names should be templates ( GET /users/{id}).

Sample Output#

text

============================================================
  OTel Instrumentation Audit — src/
  Files scanned: 52  |  Files with issues: 9
============================================================

── HIGH (3) ────────────────────────────────────────────────
🟠 OT001 [HIGH] <project>
   No OpenTelemetry SDK imported anywhere. Zero instrumentation.
   Fix: npm install @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node
        Create instrumentation.js and require it first in your entry point.

🟠 OT004 [HIGH] src/handlers/orders.js:78
   Exception caught in catch block but span.recordException() not called.
   Fix: catch (err) { span.recordException(err); span.setStatus({ code: SpanStatusCode.ERROR }); throw err; }

🟠 OT002 [HIGH] src/routes/payments.js:12
   HTTP handler (app.post /checkout) has no custom span. Business logic is a trace black box.
   Fix: tracer.startActiveSpan('checkout.process', async (span) => { ... span.end(); })

── MEDIUM (2) ──────────────────────────────────────────────
🟡 OT005 [MEDIUM] src/tracing.js:8
   OTel Resource initialized without service.name attribute.
   Fix: Resource.create({ [SemanticResourceAttributes.SERVICE_NAME]: 'payment-service' })

🟡 OT007 [MEDIUM] src/services/inventory.js:45
   span.end() called in error branch without span.setStatus(SpanStatusCode.ERROR).
   Fix: span.setStatus({ code: SpanStatusCode.ERROR, message: err.message }); span.end();

── LOW (1) ─────────────────────────────────────────────────
🔵 OT010 [LOW] src/handlers/users.js:23
   High-cardinality span name: tracer.startSpan(`GET /users/${userId}`)
   Fix: Use template: tracer.startSpan('GET /users/{id}') and set userId as span attribute.

────────────────────────────────────────────────────────────
  Total: 6 findings
  High: 3 | Medium: 2 | Low: 1

  ❌ CI GATE FAILED — resolve HIGH findings before merging.

The Script#

python

#!/usr/bin/env python3
"""
phy-otel-audit — OpenTelemetry Instrumentation Coverage Auditor
Scans Node.js/Python/Go/Java for missing or misconfigured OTel instrumentation.
Zero external dependencies.
"""

import sys
import re
from dataclasses import dataclass, field
from pathlib import Path

# ─── Data Structures ─────────────────────────────────────────────────────────

@dataclass
class Finding:
    check_id: str
    severity: str      # HIGH / MEDIUM / LOW
    location: str
    message: str
    fix: str = ""

    def __str__(self) -> str:
        icon = {"HIGH": "🟠", "MEDIUM": "🟡", "LOW": "🔵"}.get(self.severity, "⚪")
        parts = [f"{icon} {self.check_id} [{self.severity}] {self.location}"]
        parts.append(f"   {self.message}")
        if self.fix:
            parts.append(f"   Fix: {self.fix}")
        return "\n".join(parts)

@dataclass
class AuditResult:
    scan_root: str
    files_scanned: int = 0
    files_flagged: int = 0
    findings: list = field(default_factory=list)

    @property
    def high_count(self) -> int:
        return sum(1 for f in self.findings if f.severity == "HIGH")

    @property
    def medium_count(self) -> int:
        return sum(1 for f in self.findings if f.severity == "MEDIUM")

    @property
    def low_count(self) -> int:
        return sum(1 for f in self.findings if f.severity == "LOW")

# ─── Constants ────────────────────────────────────────────────────────────────

OTEL_IMPORT_RE = re.compile(
    r"(@opentelemetry/api|@opentelemetry/sdk-node|@opentelemetry/auto-instrumentations|"
    r"from opentelemetry|import opentelemetry|go\.opentelemetry\.io/otel|"
    r"io\.opentelemetry|opentelemetry-java)",
    re.IGNORECASE,
)

HTTP_HANDLER_RE = re.compile(
    r"""(app|router|r|e|g|mux)\.(get|post|put|patch|delete|handle)\s*\(\s*['"`/]""",
    re.IGNORECASE,
)

PYTHON_ROUTE_RE = re.compile(
    r"""@(app|router|blueprint)\.(get|post|put|patch|delete|route)\s*\(""",
    re.IGNORECASE,
)

GO_ROUTE_RE = re.compile(
    r"""(router|r|mux|e)\.(GET|POST|PUT|PATCH|DELETE|Handle)\s*\(""",
)

SPRING_HANDLER_RE = re.compile(
    r"@(GetMapping|PostMapping|PutMapping|PatchMapping|DeleteMapping|RequestMapping)",
)

DB_CALL_RE = re.compile(
    r"(db\.query|db\.execute|db\.find|db\.save|db\.update|db\.delete|"
    r"prisma\.\w+\.(find|create|update|delete|upsert)|"
    r"mongoose\.\w+\.(find|save|update|delete)|"
    r"cursor\.execute|session\.execute|"
    r"db\.Execute|db\.Query|db\.QueryRow|"
    r"redis\.(get|set|del|hget|hset)|"
    r"cache\.(get|set|delete)|"
    r"\.findById|\.findOne|\.findAll|\.save\(\)|\.delete\(\))",
    re.IGNORECASE,
)

SPAN_ACTIVE_RE = re.compile(
    r"(tracer\.(startActiveSpan|startSpan)|"
    r"with\s+tracer\.start_as_current_span|"
    r"otel\.trace\.getActiveSpan|"
    r"span\s*:?=\s*tracer\.Start|"
    r"@WithSpan|@NewSpan)",
    re.IGNORECASE,
)

CATCH_BLOCK_RE = re.compile(r"(catch\s*\(|except\s+\w|except\s*:)", re.IGNORECASE)

EXCEPTION_RECORD_RE = re.compile(
    r"(span\.recordException|span\.record_exception|span\.RecordError)",
    re.IGNORECASE,
)

SPAN_STATUS_ERROR_RE = re.compile(
    r"(span\.setStatus|span\.set_status|span\.SetStatus)",
    re.IGNORECASE,
)

RESOURCE_INIT_RE = re.compile(
    r"(Resource\.create|Resource\.default\(\)|new Resource|resource\.New)",
    re.IGNORECASE,
)

SERVICE_NAME_RE = re.compile(
    r"(SERVICE_NAME|service\.name|service_name\s*:|\"service\.name\")",
    re.IGNORECASE,
)

CONSOLE_EXPORTER_RE = re.compile(
    r"(ConsoleSpanExporter|ConsoleMetricExporter|ConsoleLogRecordExporter|"
    r"StdoutSpanExporter|stdout_span_exporter)",
    re.IGNORECASE,
)

ASYNC_CONCURRENT_RE = re.compile(
    r"(Promise\.all\s*\(|Promise\.allSettled\s*\(|asyncio\.gather\s*\(|"
    r"go\s+func\s*\(|go\s+\w+\()",
    re.IGNORECASE,
)

CONTEXT_PASS_RE = re.compile(
    r"(context\.TODO\(\)|context\.Background\(\)|ctx,|propagation\.|"
    r"W3CTraceContextPropagator|TraceContext\.inject|extract\()",
    re.IGNORECASE,
)

SPAN_START_WITH_TEMPLATE_RE = re.compile(
    r"""tracer\.(startSpan|startActiveSpan)\s*\(\s*[`'"].*(\$\{|\%s|\+\s*\w+)""",
)

SPAN_END_RE = re.compile(r"span\.(end|End)\(\)", re.IGNORECASE)

DEV_CONFIG_PATTERN = re.compile(
    r"(dev|development|test|local|debug)",
    re.IGNORECASE,
)

OTEL_INIT_FILE_RE = re.compile(
    r"(tracing|instrumentation|telemetry|otel)(\.(js|ts|py))?$",
    re.IGNORECASE,
)

REQUIRE_RE = re.compile(r"require\s*\(['\"]([^'\"]+)['\"]\)")

SUPPORTED_EXTENSIONS = {".js", ".ts", ".jsx", ".tsx", ".mjs", ".py", ".go", ".java", ".kt"}
SKIP_DIRS = {"node_modules", ".git", "venv", ".venv", "__pycache__", "dist", "build", ".next", "vendor", "test", "tests", "__tests__"}

# ─── Helpers ─────────────────────────────────────────────────────────────────

def get_context_lines(lines: list, idx: int, window: int = 20) -> str:
    start = max(0, idx - window)
    end = min(len(lines), idx + window)
    return "\n".join(lines[start:end])

def collect_files(path: str) -> list:
    p = Path(path)
    if p.is_file():
        return [p] if p.suffix in SUPPORTED_EXTENSIONS else []
    files = []
    for f in p.rglob("*"):
        if any(skip in f.parts for skip in SKIP_DIRS):
            continue
        if f.is_file() and f.suffix in SUPPORTED_EXTENSIONS:
            files.append(f)
    return files

def is_dev_config_file(filepath: str) -> bool:
    """Heuristic: is this a dev/test config file?"""
    name = Path(filepath).name.lower()
    return bool(DEV_CONFIG_PATTERN.search(name))

# ─── Checks ──────────────────────────────────────────────────────────────────

def check_ot001_no_otel_sdk(all_contents: dict) -> list:
    """OT001 — No OTel SDK imported anywhere."""
    for content in all_contents.values():
        if OTEL_IMPORT_RE.search(content):
            return []
    return [Finding(
        check_id="OT001",
        severity="HIGH",
        location="<project>",
        message="No OpenTelemetry SDK imported anywhere. Zero instrumentation — no traces, metrics, or logs exported.",
        fix=(
            "JS: npm install @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node\n"
            "   Python: pip install opentelemetry-sdk opentelemetry-exporter-otlp\n"
            "   Go: go get go.opentelemetry.io/otel go.opentelemetry.io/otel/exporters/otlp/otlptrace"
        ),
    )]

def check_ot002_handler_no_span(filepath: str, lines: list) -> list:
    """OT002 — HTTP handler without custom span."""
    findings = []
    for i, line in enumerate(lines):
        is_handler = (
            HTTP_HANDLER_RE.search(line) or
            PYTHON_ROUTE_RE.search(line) or
            GO_ROUTE_RE.search(line) or
            SPRING_HANDLER_RE.search(line)
        )
        if not is_handler:
            continue
        ctx = get_context_lines(lines, i, 30)
        if not SPAN_ACTIVE_RE.search(ctx):
            findings.append(Finding(
                check_id="OT002",
                severity="HIGH",
                location=f"{filepath}:{i + 1}",
                message=f"HTTP handler '{line.strip()[:70]}' has no custom span. Business logic inside is a trace black box.",
                fix="tracer.startActiveSpan('handler.name', async (span) => { try { ... } finally { span.end(); } })",
            ))
    return findings

def check_ot003_db_outside_span(filepath: str, lines: list) -> list:
    """OT003 — DB/cache call where no span context is active in scope."""
    findings = []
    for i, line in enumerate(lines):
        if not DB_CALL_RE.search(line):
            continue
        ctx = get_context_lines(lines, i, 30)
        if not SPAN_ACTIVE_RE.search(ctx):
            findings.append(Finding(
                check_id="OT003",
                severity="HIGH",
                location=f"{filepath}:{i + 1}",
                message=f"DB/cache call '{line.strip()[:70]}' outside an active span — DB timing won't appear in traces.",
                fix="Wrap DB calls inside tracer.startActiveSpan('db.query') or ensure callers always create a span first.",
            ))
    return findings

def check_ot004_exception_not_recorded(filepath: str, lines: list) -> list:
    """OT004 — Exception caught without span.recordException()."""
    findings = []
    for i, line in enumerate(lines):
        if not CATCH_BLOCK_RE.search(line):
            continue
        ctx = get_context_lines(lines, i, 15)
        # Only flag if there's a span in scope
        if not SPAN_ACTIVE_RE.search(ctx) and "span" not in ctx.lower():
            continue
        if not EXCEPTION_RECORD_RE.search(ctx):
            findings.append(Finding(
                check_id="OT004",
                severity="HIGH",
                location=f"{filepath}:{i + 1}",
                message="Exception caught inside a span scope but span.recordException() not called. Trace appears successful on error.",
                fix="catch (err) { span.recordException(err); span.setStatus({ code: SpanStatusCode.ERROR, message: err.message }); throw err; }",
            ))
    return findings

def check_ot005_no_service_name(filepath: str, lines: list, content: str) -> list:
    """OT005 — OTel Resource initialized without service.name."""
    if not RESOURCE_INIT_RE.search(content):
        return []
    if SERVICE_NAME_RE.search(content):
        return []
    # Resource init found but no service.name
    for i, line in enumerate(lines):
        if RESOURCE_INIT_RE.search(line):
            return [Finding(
                check_id="OT005",
                severity="MEDIUM",
                location=f"{filepath}:{i + 1}",
                message="OTel Resource initialized without service.name. All traces appear as 'unknown_service' in Jaeger/Tempo/Honeycomb.",
                fix="Resource.create({ [SemanticResourceAttributes.SERVICE_NAME]: 'my-service-name' })",
            )]
    return []

def check_ot006_sdk_late_init(filepath: str, lines: list) -> list:
    """OT006 — OTel SDK initialized after other imports (Node.js only)."""
    if not filepath.endswith((".js", ".ts", ".mjs")):
        return []
    # Only check entry files (server.js, index.js, app.js, main.js)
    name = Path(filepath).stem.lower()
    if name not in ("server", "index", "app", "main", "start"):
        return []

    requires = []
    for i, line in enumerate(lines):
        m = REQUIRE_RE.search(line)
        if m:
            requires.append((i, m.group(1)))

    otel_idx = None
    first_other_idx = None
    for idx, module in requires:
        if "opentelemetry" in module or "tracing" in module or "instrumentation" in module:
            if otel_idx is None:
                otel_idx = idx
        else:
            if first_other_idx is None:
                first_other_idx = idx

    if otel_idx is not None and first_other_idx is not None and otel_idx > first_other_idx:
        return [Finding(
            check_id="OT006",
            severity="MEDIUM",
            location=f"{filepath}:{otel_idx + 1}",
            message="OTel SDK initialized AFTER other imports. Auto-instrumentation patches miss already-loaded modules.",
            fix="Move require('./tracing') to the very first line of your entry file, before any other require().",
        )]
    return []

def check_ot007_span_end_no_status(filepath: str, lines: list) -> list:
    """OT007 — span.end() in error branch without setStatus(ERROR)."""
    findings = []
    for i, line in enumerate(lines):
        if not SPAN_END_RE.search(line):
            continue
        # Check if inside an error branch
        ctx_before = "\n".join(lines[max(0, i - 10):i])
        if not re.search(r"(catch|except|error|err|Error|Exception)", ctx_before, re.IGNORECASE):
            continue
        if not SPAN_STATUS_ERROR_RE.search(ctx_before):
            findings.append(Finding(
                check_id="OT007",
                severity="MEDIUM",
                location=f"{filepath}:{i + 1}",
                message="span.end() in error branch without span.setStatus(SpanStatusCode.ERROR). Span marked OK despite error.",
                fix="span.setStatus({ code: SpanStatusCode.ERROR, message: err.message }); span.end();",
            ))
    return findings

def check_ot008_async_context_not_passed(filepath: str, lines: list) -> list:
    """OT008 — Concurrent async without context propagation (Go goroutines)."""
    findings = []
    # Only relevant for Go files (Python asyncio propagates automatically via contextvars)
    if not filepath.endswith(".go"):
        return []
    for i, line in enumerate(lines):
        if not re.search(r"^(\s*)go\s+(func|\w+)\s*\(", line):
            continue
        ctx = get_context_lines(lines, i, 15)
        # Check if ctx is passed into the goroutine
        if not re.search(r"ctx|context\.Context|trace\.SpanFromContext", ctx):
            findings.append(Finding(
                check_id="OT008",
                severity="MEDIUM",
                location=f"{filepath}:{i + 1}",
                message="Goroutine launched without passing context.Context — OTel trace context is lost in this goroutine.",
                fix="go func(ctx context.Context) { ... }(ctx)  — always thread ctx through goroutines.",
            ))
    return findings

def check_ot009_console_exporter(filepath: str, lines: list) -> list:
    """OT009 — Console/stdout exporter in non-dev file."""
    if is_dev_config_file(filepath):
        return []
    findings = []
    for i, line in enumerate(lines):
        if CONSOLE_EXPORTER_RE.search(line):
            findings.append(Finding(
                check_id="OT009",
                severity="LOW",
                location=f"{filepath}:{i + 1}",
                message="ConsoleSpanExporter detected outside dev config. Console exporter floods logs with no backend value in production.",
                fix="Replace with OTLPTraceExporter pointing to your Jaeger/Tempo/Honeycomb/Grafana Cloud endpoint.",
            ))
    return findings

def check_ot010_high_cardinality_span_name(filepath: str, lines: list) -> list:
    """OT010 — High-cardinality span name (dynamic values in name string)."""
    findings = []
    for i, line in enumerate(lines):
        if SPAN_START_WITH_TEMPLATE_RE.search(line):
            findings.append(Finding(
                check_id="OT010",
                severity="LOW",
                location=f"{filepath}:{i + 1}",
                message=f"Span name uses dynamic value: '{line.strip()[:80]}'. High-cardinality names break trace aggregation in backends.",
                fix="Use fixed template: tracer.startSpan('GET /users/{id}') and add userId as a span attribute: span.setAttribute('user.id', userId)",
            ))
    return findings

# ─── Main Audit ───────────────────────────────────────────────────────────────

def audit(path: str) -> AuditResult:
    result = AuditResult(scan_root=path)
    files = collect_files(path)

    all_contents = {}
    for f in files:
        try:
            all_contents[str(f)] = f.read_text(errors="ignore")
        except Exception:
            pass

    result.files_scanned = len(files)

    # Global check
    result.findings.extend(check_ot001_no_otel_sdk(all_contents))

    # Per-file checks
    for f in files:
        content = all_contents.get(str(f), "")
        lines = content.splitlines()
        fp = str(f)

        file_findings = []
        file_findings.extend(check_ot002_handler_no_span(fp, lines))
        file_findings.extend(check_ot003_db_outside_span(fp, lines))
        file_findings.extend(check_ot004_exception_not_recorded(fp, lines))
        file_findings.extend(check_ot005_no_service_name(fp, lines, content))
        file_findings.extend(check_ot006_sdk_late_init(fp, lines))
        file_findings.extend(check_ot007_span_end_no_status(fp, lines))
        file_findings.extend(check_ot008_async_context_not_passed(fp, lines))
        file_findings.extend(check_ot009_console_exporter(fp, lines))
        file_findings.extend(check_ot010_high_cardinality_span_name(fp, lines))

        if file_findings:
            result.files_flagged += 1
        result.findings.extend(file_findings)

    return result

def format_report(result: AuditResult, ci_mode: bool = False) -> str:
    out = []
    out.append(f"\n{'='*60}")
    out.append(f"  OTel Instrumentation Audit — {result.scan_root}")
    out.append(f"  Files scanned: {result.files_scanned}  |  Files with issues: {result.files_flagged}")
    out.append(f"{'='*60}")

    if not result.findings:
        out.append("✅ No OTel instrumentation gaps detected.")
        return "\n".join(out)

    for severity in ("HIGH", "MEDIUM", "LOW"):
        sev_findings = [f for f in result.findings if f.severity == severity]
        if sev_findings:
            out.append(f"\n── {severity} ({len(sev_findings)}) {'─'*40}")
            for finding in sev_findings:
                out.append(str(finding))

    out.append(f"\n{'─'*60}")
    out.append(
        f"  Total: {len(result.findings)} findings  |  "
        f"High: {result.high_count}  Medium: {result.medium_count}  Low: {result.low_count}"
    )
    if ci_mode and result.high_count > 0:
        out.append("\n  ❌ CI GATE FAILED — resolve HIGH findings before merging.")
    return "\n".join(out)

# ─── CLI ─────────────────────────────────────────────────────────────────────

def main():
    import argparse

    parser = argparse.ArgumentParser(
        description="phy-otel-audit — OpenTelemetry Instrumentation Auditor",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  python otel_audit.py ./src
  python otel_audit.py src/handlers/orders.js
  python otel_audit.py ./src --ci
  python otel_audit.py ./src --only-severity HIGH
        """,
    )
    parser.add_argument("path", help="Directory or file to audit")
    parser.add_argument("--ci", action="store_true", help="Exit 1 on HIGH findings")
    parser.add_argument(
        "--only-severity",
        choices=["HIGH", "MEDIUM", "LOW"],
        help="Filter to this severity and above",
    )
    args = parser.parse_args()

    result = audit(args.path)

    sev_order = ["HIGH", "MEDIUM", "LOW"]
    if args.only_severity:
        cutoff = sev_order.index(args.only_severity)
        result.findings = [f for f in result.findings if sev_order.index(f.severity) <= cutoff]

    print(format_report(result, ci_mode=args.ci))

    if args.ci and result.high_count > 0:
        sys.exit(1)

if __name__ == "__main__":
    main()

CI Integration#

yaml

# GitHub Actions
- name: OTel Instrumentation Audit
  run: python otel_audit.py ./src --ci

# Only block on HIGH
- name: OTel Audit (strict)
  run: python otel_audit.py ./src --only-severity HIGH --ci

False Positive Notes#

• OT002 — If you use auto-instrumentation exclusively (e.g., @opentelemetry/auto-instrumentations-node), framework-level spans are created automatically. OT002 fires because it can't see the auto-instrumentation wrapper. Suppress with # phy-ignore: OT002 on the route line if auto-instrumentation is confirmed.
• OT003 — DB calls in utility functions called from within spans will false-positive (the span context exists at runtime but isn't visible in the static 30-line window). Check actual trace output to confirm.
• OT006 — Only checks Node.js entry files named server, index, app, main, start.
• OT008 — Only checks Go goroutines. Python asyncio propagates context automatically via contextvars.

Related Skills#

• phy-async-audit — async error propagation (unhandled exceptions in spans)
• phy-log-smell-auditor — structured logging gaps that complement OTel spans
• phy-rate-limit-audit — rate limit signals visible in OTel metrics

---

Author#

Canlah AI — Run performance marketing without breaking your brand.

• GitHub: github.com/PHY041
• All Skills: clawhub.ai/PHY041