Skip to content

ADR-0003: Activate Telemetry via Environment Variable (Mandatory but Zero-Config)

Status: accepted Deciders: DeAcero Platform Team Date: 2026-03-17 Parent: ADR-0001

Context and Problem Statement

Telemetry must be unobtrusive. A team that generates a project without configuring observability must not have their CI fail, their builds slow down, or their code error out. At the same time, DeAcero wants all teams to eventually report to the central service. How do we make telemetry mandatory at the organization level while keeping it completely transparent to individual projects?

Considered Options

  1. Environment variable gate (AGENTIC_TELEMETRY_URL) — telemetry is active iff the var is set; silent no-op otherwise
  2. Explicit opt-in in cookiecutter.json — teams must set a boolean during generation
  3. Hardcoded URL at generation time — the URL is baked in at cookiecutter generation; always active

Decision Outcome

Chosen option: Option 1 — Environment variable gate.

Rationale: Option 3 (hardcoded URL) would force every project to have a live observability server reachable from CI, breaking projects that haven't onboarded yet. Option 2 (explicit opt-in) requires every team to take an action, which reduces adoption. Option 1 is the best of both: the org configures AGENTIC_TELEMETRY_URL as a GitHub organization secret or CI environment variable, and all projects automatically start reporting the moment the secret is provisioned — without any project-level code change. Teams that haven't been onboarded simply don't have the variable and see zero impact.

Behavior Contract

AGENTIC_TELEMETRY_URL not set → send_event() is a complete no-op (no network call, no log)
AGENTIC_TELEMETRY_URL = ""    → treated as not set (empty string = disabled)
AGENTIC_TELEMETRY_URL = URL   → events are posted to URL/v1/events in a background thread
Network error or timeout      → swallowed silently; never raises; never blocks CI

Positive Consequences

  • Zero impact on existing projects until the org secret is provisioned
  • Org-wide rollout is a single secret update, not a PR per project
  • Fire-and-forget threading means CI pipelines are never slowed by telemetry
  • Works identically for local dev (env var unset → no phone-home)

Negative Consequences

  • No feedback to the team when telemetry is silently failing (mitigated: GET /health endpoint and optional stderr logging behind AGENTIC_TELEMETRY_DEBUG=1)
  • Relies on CI secret management (GitHub Actions secrets or equivalent) — teams without secrets management must set the var manually
  • Parent: ADR-0001
  • Implementation: {{cookiecutter.project_slug}}/.telemetry/client.py → is_telemetry_enabled()
  • CI integration: {{cookiecutter.project_slug}}/.github/workflows/ci.yml → AGENTIC_TELEMETRY_URL: ${{ secrets.AGENTIC_TELEMETRY_URL }}