Sentry Instrumentation

Sentry system metrics only (counter / gauge / distribution, duration, failure, resource). Product-analytics events (clicks, funnels, flag exposure) belong in your product-analytics tool — never in Sentry. Python under examples/python/ is the canonical reference; other languages port the same shapes under idiomatic names.

Do not invoke for product-analytics changes. Stop and use the right tool.

Decision rules

1. New metric? Read references/signal-model.md and pick a classmethod constructor (MetricDef.counter|latency|gauge|resource|failure_counter). Register in the project's metric registry. Never call an emission helper with a raw string or a dynamically-assembled name.
2. Tag values? Either enumerate them in MetricDef.tag_constraints or route through a bucket function from references/tagging-and-cardinality.md.
3. Inside a loop? Use AggregatingCounter or DurationAccumulator (see references/cost-model.md). If the metric's loop_policy is "forbidden" the CI gate refuses any emission inside a for/while body for that metric.
4. New surface (HTTP route / external API / workflow step / retry / fallback)? Use the matching reusable pattern from references/surface-patterns.md. Don't hand-roll the emissions.
5. Changing a metric's meaning, unit, or tag shape? It's a new versioned metric. See references/naming-and-lifecycle.md.
6. Failure counter? Build with MetricDef.failure_counter(...) and emit with emit_failure(metric, failure=classify(exc), tags=...). Never pass str(exc) as a tag. See references/failure-taxonomy.md.

Language detection

Detect the project language from manifest files, then extend any existing observability layer you find (observability.py / observability.ts / metrics/ package). If none exists, scaffold from the matching example directory.

pyproject.toml / setup.py  → Python. Use examples/python/.
package.json               → TypeScript/JavaScript. Port from examples/python/ shapes.
go.mod                     → Go. Port from examples/python/ shapes.
Gemfile                    → Ruby. Port from examples/python/ shapes.
pom.xml / build.gradle     → Java/Kotlin. Port from examples/python/ shapes.

For ports: preserve the five constructors, the FailureClass taxonomy values, the 13 CI gate checks, and the emission-boundary rules. Names become idiomatic (emit_counter → emitCounter, @instrumented_step → instrumentedStep(fn), etc.).

Python project paths (canonical reference)

Replace yourapp with the project's package root on first use.

Emission module:    yourapp/observability.py
Registry:           yourapp/shared/metrics.py
Tag buckets:        yourapp/shared/metric_tags.py
Failure taxonomy:   yourapp/shared/failure_taxonomy.py
HTTP middleware:    yourapp/middleware/observability.py
Workflow decorator: yourapp/services/<workflow>/instrumentation.py
External API base:  yourapp/services/providers/instrumented_http_client.py
Retry helper:       yourapp/services/retry.py
Fallback helper:    yourapp/observability.py (or yourapp/shared/fallback.py)
CI gate:            scripts/check_metrics.py

References (load on demand)