Phy Otel Audit

OpenTelemetry instrumentation coverage auditor. Scans Node.js/Python/Go/Java source code to detect missing or misconfigured OTel instrumentation — HTTP handlers without spans, database calls outside trace context, missing resource attributes, span errors not recorded, baggage not propagated, SDK not initialized before first import, sampler misconfiguration, and more. Outputs a per-file coverage score and actionable fix snippets. Zero external dependencies.

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

ID	Severity	Check
OT001	HIGH	No OTel SDK imported anywhere — zero instrumentation
OT002	HIGH	HTTP handler without span creation
OT003	HIGH	Database/cache call outside active span
OT004	HIGH	Exception caught but span.recordException() not called
OT005	MEDIUM	service.name not set in Resource attributes
OT006	MEDIUM	OTel SDK initialized after first import (instrumentation gap)
OT007	MEDIUM	Span created but status not set on error path
OT008	MEDIUM	Async context propagation missing (Promise/goroutine context not passed)
OT009	LOW	Trace exporter using console/stdout in non-dev environment
OT010	LOW	Manual 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