carros-ai-utils 0.2.0__tar.gz

carros_ai_utils-0.2.0/.github/workflows/pr-agent.yml

@@ -0,0 +1,22 @@
+name: PR Agent
+
+on:
+  pull_request:
+    types: [opened, reopened, ready_for_review, synchronize]
+  issue_comment:
+
+permissions:
+  issues: write
+  pull-requests: write
+  contents: read
+
+jobs:
+  review:
+    uses: carros-ai/platform-ci-workflows/.github/workflows/pr-agent.yml@main
+    permissions:
+      issues: write
+      pull-requests: write
+      contents: read
+    secrets:
+      ANTHROPIC_KEY: ${{ secrets.ANTHROPIC_KEY }}
+

carros_ai_utils-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Build
+        run: pip install build && python -m build
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

carros_ai_utils-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+*.egg-info/
+.env
+.env.*
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+.coverage

carros_ai_utils-0.2.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: carros-ai-utils
+Version: 0.2.0
+Summary: Opinionated OpenTelemetry wrapper for carros-ai Python services
+Requires-Python: >=3.11
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.25.0
+Requires-Dist: opentelemetry-instrumentation-logging>=0.46b0
+Requires-Dist: opentelemetry-sdk>=1.25.0
+Provides-Extra: dev
+Requires-Dist: bandit>=1.7; extra == 'dev'
+Requires-Dist: fastapi>=0.111.0; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: opentelemetry-exporter-prometheus>=0.46b0; extra == 'dev'
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.46b0; extra == 'dev'
+Requires-Dist: prometheus-client>=0.20; extra == 'dev'
+Requires-Dist: pydantic-settings>=2.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: structlog>=23.0; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.111.0; extra == 'fastapi'
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.46b0; extra == 'fastapi'
+Provides-Extra: prometheus
+Requires-Dist: opentelemetry-exporter-prometheus>=0.46b0; extra == 'prometheus'
+Requires-Dist: prometheus-client>=0.20; extra == 'prometheus'
+Provides-Extra: settings
+Requires-Dist: pydantic-settings>=2.0; extra == 'settings'
+Provides-Extra: structlog
+Requires-Dist: structlog>=23.0; extra == 'structlog'

carros_ai_utils-0.2.0/README.md

@@ -0,0 +1,109 @@
+# carros-ai-utils
+
+Opinionated OpenTelemetry wrapper for carros-ai Python services. Single call wires traces, metrics, and logs — all exported via OTLP gRPC to the observability collector.
+
+## Installation
+
+```toml
+# pyproject.toml
+[project]
+dependencies = [
+    "carros-ai-utils @ git+ssh://git@github.com/carros-ai/python-utils.git",
+]
+```
+
+With FastAPI support:
+
+```toml
+dependencies = [
+    "carros-ai-utils[fastapi] @ git+ssh://git@github.com/carros-ai/python-utils.git",
+]
+```
+
+## Usage
+
+### FastAPI
+
+```python
+# main.py
+from contextlib import asynccontextmanager
+
+import carros_ai_utils
+from carros_ai_utils.fastapi import instrument_fastapi
+from fastapi import FastAPI
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    carros_ai_utils.init("payments-api")
+    instrument_fastapi(app, "payments-api")
+    yield
+    carros_ai_utils.shutdown()
+
+
+app = FastAPI(lifespan=lifespan)
+```
+
+### Plain Python / scripts
+
+```python
+import carros_ai_utils
+
+carros_ai_utils.init("my-worker")
+
+# traces
+with carros_ai_utils.tracer("my-module").start_as_current_span("process-job") as span:
+    span.set_attribute("job.id", job_id)
+    do_work()
+
+# metrics
+counter = carros_ai_utils.meter("my-module").create_counter("jobs.processed")
+counter.add(1, {"queue": "default"})
+
+carros_ai_utils.shutdown()
+```
+
+### Logging
+
+After `carros_ai_utils.init()`, Python's standard `logging` module is automatically bridged to OTLP. No extra setup needed:
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+logger.info("job started", extra={"job_id": "abc123"})
+```
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | `localhost:4317` | Collector gRPC endpoint |
+| `APP_ENVIRONMENT` | `development` | Set to `production` to activate OTLP export |
+| `APP_VERSION` | `0.0.0` | Reported as `service.version` resource attribute |
+| `OTEL_SERVICE_NAME` | _(init arg)_ | Overrides the `service_name` passed to `carros_ai_utils.init()` |
+
+In **development** (default), all signals are printed to the console. In **production**, they are exported via gRPC to `OTEL_EXPORTER_OTLP_ENDPOINT`.
+
+## Kubernetes / Coolify deployment
+
+Add these env vars to your `deployment.yaml` or Coolify service:
+
+```yaml
+- name: APP_ENVIRONMENT
+  value: "production"
+- name: APP_VERSION
+  value: "1.0.0"
+- name: OTEL_EXPORTER_OTLP_ENDPOINT
+  value: "metrics-collector-api.application.svc.cluster.local:4317"
+```
+
+The `OTEL_SERVICE_NAME` is optional — if omitted, the name passed to `carros_ai_utils.init()` is used.
+
+## FastAPI middleware behavior
+
+`instrument_fastapi` automatically:
+
+- Creates a span for every HTTP request
+- Propagates trace context from incoming headers (`traceparent`)
+- Copies the `X-User-Id` header (injected by Traefik forward-auth) into the span as `enduser.id`

carros_ai_utils-0.2.0/openspec/changes/archive/2026-04-03-init-telemetry-python/design.md

@@ -0,0 +1,65 @@
+## Context
+The OpenTelemetry Python SDK requires configuring three independent providers
+(TracerProvider, MeterProvider, LoggerProvider), each with its own exporter,
+resource, and global registration. This library does all of that in one call
+and exposes a minimal, stable surface for application code.
+
+## Goals
+1. Single init() call configures all three signal types
+2. No global state leakage between tests — providers can be reset
+3. Environment-driven config — no config files, no hardcoded values
+4. Works in production (gRPC to collector) and locally (stdout, no collector needed)
+5. FastAPI integration requires zero manual span management per route
+
+## Technical Decisions
+
+### Decision: OTLP gRPC only (no HTTP exporter)
+ALTERNATIVES: Support both gRPC and HTTP
+RISKS: Environments that block HTTP/2 cannot use this library
+RATIONALE: Matches the telemetry-collector which only exposes gRPC. All
+carros-ai services run inside private Docker networks where gRPC is fully
+supported. Adding HTTP adds a second code path with no current consumer.
+
+### Decision: APP_ENVIRONMENT drives exporter selection
+ALTERNATIVES: Separate env var (e.g. OTEL_PYTHON_EXPORTER=grpc|stdout)
+RISKS: APP_ENVIRONMENT may be used for other purposes in the app
+RATIONALE: Consistent with the Go telemetry package convention already in use.
+When APP_ENVIRONMENT=production, gRPC to the collector is used. Any other
+value falls back to stdout (ConsoleExporter), allowing local development
+without running the collector.
+
+### Decision: Python logging bridge via LoggingHandler
+ALTERNATIVES: Provide a custom logger API; use structlog
+RISKS: LoggingHandler adds latency to every log call via OTLP export
+RATIONALE: Application code already uses logging.getLogger(). Bridging it
+to OTLP requires zero changes in application code — only telemetry.init()
+needs to be called at startup. Custom logger APIs would require refactoring
+every existing log call.
+
+### Decision: FastAPI middleware via OpenTelemetry FastAPI instrumentation
+ALTERNATIVES: Manual span creation in route handlers; custom ASGI middleware
+RISKS: Upstream instrumentation library may lag behind FastAPI releases
+RATIONALE: opentelemetry-instrumentation-fastapi is the official, maintained
+instrumentation. It handles span creation, HTTP attribute population, and
+error capture automatically. Manual spans would require changes in every route.
+
+### Decision: Frozen dataclass for Config (not Pydantic)
+ALTERNATIVES: Pydantic BaseSettings; plain dict; os.getenv() calls scattered
+RISKS: Less validation than Pydantic; no .env file loading
+RATIONALE: This is a library, not an application. Adding Pydantic as a
+required dependency would force it on every consumer. A frozen dataclass
+with explicit type coercion keeps the dependency footprint minimal.
+If a consumer already uses Pydantic, they can pass config values directly.
+
+## Migration
+Existing services add one dependency to pyproject.toml and one call in main:
+```python
+import telemetry
+telemetry.init("my-service")
+```
+No other changes required. Existing logging.getLogger() calls are
+automatically bridged to OTLP after init().
+
+## Open Questions
+- Should meter() expose shorthand helpers (counter, histogram) or only the raw Meter?
+- Should init() accept a shutdown_timeout parameter for graceful flush?

carros_ai_utils-0.2.0/openspec/changes/archive/2026-04-03-init-telemetry-python/proposal.md

@@ -0,0 +1,24 @@
+## Why
+Every Python service in the carros-ai platform must configure OpenTelemetry
+providers, exporters, and resource attributes individually. This is repetitive,
+error-prone, and leads to inconsistent observability across services. A shared
+library encapsulates this once — services call telemetry.init("name") and get
+fully configured traces, metrics, and logs with zero boilerplate.
+
+## What Changes
+Initial creation of the telemetry-python library. No existing services are
+modified. All capabilities are ADDED.
+
+## Capabilities
+- **config** — Reads observability settings from environment variables with sensible defaults
+- **otlp-exporter** — Configures OTLP gRPC exporters pointing to the telemetry-collector
+- **init** — Single entry point that wires all providers with one function call
+- **tracer** — Provides a pre-configured Tracer for creating spans
+- **meter** — Provides a pre-configured Meter for recording metrics
+- **logger** — Bridges Python standard logging to OTLP via LoggingHandler
+- **fastapi-middleware** — Auto-instruments FastAPI apps (spans per request, error capture)
+
+## Impact
+- New standalone library — no existing services are modified
+- Services add one dependency and one init() call at startup
+- Requires the telemetry-collector to be reachable at OTEL_EXPORTER_OTLP_ENDPOINT

carros_ai_utils-0.2.0/openspec/changes/archive/2026-04-03-init-telemetry-python/specs/config/spec.md

@@ -0,0 +1,55 @@
+## Purpose
+Read observability settings from environment variables and expose them as an
+immutable Config object. Provides sensible defaults so services work locally
+without any environment setup.
+
+### Requirement: Config from Environment Variables
+The library SHALL read configuration exclusively from environment variables,
+applying defaults for any variable that is not set.
+
+#### Scenario: All defaults applied when no env vars set
+- **GIVEN** no observability-related environment variables are set
+- **WHEN** Config is instantiated
+- **THEN** `endpoint` is `"localhost:4317"`
+- **AND** `environment` is `"development"`
+- **AND** `version` is `"0.0.0"`
+- **AND** `service_name` is `None` (overridden by init() argument)
+
+#### Scenario: Production values read from environment
+- **GIVEN** the following env vars are set:
+  ```
+  OTEL_EXPORTER_OTLP_ENDPOINT=telemetry-collector:4317
+  APP_ENVIRONMENT=production
+  APP_VERSION=1.2.3
+  OTEL_SERVICE_NAME=payments-api
+  ```
+- **WHEN** Config is instantiated
+- **THEN** each field reflects the corresponding env var value
+
+#### Scenario: OTEL_SERVICE_NAME overrides init() argument
+- **GIVEN** `OTEL_SERVICE_NAME=env-name` is set
+- **WHEN** `telemetry.init("code-name")` is called
+- **THEN** the effective service name used in the resource is `"env-name"`
+
+### Requirement: Immutable Config
+The Config object SHALL be immutable after instantiation — no field may be
+modified by application code.
+
+#### Scenario: Mutation attempt raises error
+- **GIVEN** a Config instance
+- **WHEN** application code attempts to set any field (e.g. `cfg.endpoint = "x"`)
+- **THEN** a `FrozenInstanceError` or `AttributeError` is raised
+
+### Requirement: Production Mode Detection
+The library SHALL treat `APP_ENVIRONMENT=production` as the signal to use
+gRPC OTLP export. Any other value (including unset) uses stdout export.
+
+#### Scenario: Production mode active
+- **GIVEN** `APP_ENVIRONMENT=production`
+- **WHEN** `config.is_production` is accessed
+- **THEN** it returns `True`
+
+#### Scenario: Development mode when env var absent
+- **GIVEN** `APP_ENVIRONMENT` is not set
+- **WHEN** `config.is_production` is accessed
+- **THEN** it returns `False`

carros_ai_utils-0.2.0/openspec/changes/archive/2026-04-03-init-telemetry-python/specs/fastapi-middleware/spec.md

@@ -0,0 +1,58 @@
+## Purpose
+Provide zero-config FastAPI auto-instrumentation that creates a span per
+HTTP request, captures standard HTTP attributes, and records errors —
+without requiring manual span management in route handlers.
+
+### Requirement: Automatic Span per Request
+After instrumentation is applied, the library SHALL create an OTel span for
+every incoming HTTP request handled by FastAPI.
+
+#### Scenario: Span created for successful request
+- **GIVEN** `telemetry.init("api")` was called and instrumentation applied
+- **WHEN** a GET request to `/items/42` is handled and returns 200
+- **THEN** a span named `"GET /items/{item_id}"` is created
+- **AND** it has attributes: `http.method=GET`, `http.status_code=200`,
+  `http.route=/items/{item_id}`
+- **AND** the span status is OK
+
+#### Scenario: Span records 5xx errors
+- **GIVEN** instrumentation is applied
+- **WHEN** a route raises an unhandled exception (500)
+- **THEN** the span status is set to ERROR
+- **AND** the exception is recorded on the span via `span.record_exception()`
+
+#### Scenario: Span records 4xx without error status
+- **GIVEN** instrumentation is applied
+- **WHEN** a route returns 404
+- **THEN** the span is created with `http.status_code=404`
+- **AND** the span status is NOT set to ERROR (4xx are not server errors)
+
+### Requirement: Lifespan Integration
+The library SHALL provide a FastAPI lifespan context manager that calls
+`telemetry.init()` on startup and `telemetry.shutdown()` on shutdown.
+
+#### Scenario: Init called on app startup
+- **GIVEN** a FastAPI app uses `telemetry.fastapi.lifespan("svc")`
+- **WHEN** the app starts
+- **THEN** `telemetry.init("svc")` is called before the first request
+
+#### Scenario: Shutdown called on app shutdown
+- **GIVEN** a FastAPI app uses `telemetry.fastapi.lifespan("svc")`
+- **WHEN** the app receives SIGTERM and begins shutdown
+- **THEN** `telemetry.shutdown()` is called, flushing pending signals
+
+### Requirement: Opt-in Instrumentation
+Instrumentation SHALL NOT be applied automatically on import — the application
+must explicitly call the instrumentation function or use the lifespan helper.
+
+#### Scenario: Import does not instrument
+- **GIVEN** `import telemetry.fastapi` was executed
+- **WHEN** no instrumentation call is made
+- **THEN** no spans are created for requests
+- **AND** no global state is modified
+
+#### Scenario: Explicit instrumentation applies
+- **GIVEN** an existing FastAPI app instance `app`
+- **WHEN** `telemetry.fastapi.instrument(app)` is called
+- **THEN** the FastAPIInstrumentor is applied to `app`
+- **AND** all subsequent requests generate spans

carros_ai_utils-0.2.0/openspec/changes/archive/2026-04-03-init-telemetry-python/specs/init/spec.md

@@ -0,0 +1,51 @@
+## Purpose
+Provide a single entry point that configures all OpenTelemetry providers
+(traces, metrics, logs) and registers them globally, so application code
+needs only one call at startup.
+
+### Requirement: Single Init Call
+The library SHALL expose `telemetry.init(service_name)` as the sole required
+setup call. After this call, traces, metrics, and logs are fully configured.
+
+#### Scenario: Init configures all three providers
+- **GIVEN** no providers have been configured
+- **WHEN** `telemetry.init("payments-api")` is called
+- **THEN** a TracerProvider is set as the global OTel tracer provider
+- **AND** a MeterProvider is set as the global OTel meter provider
+- **AND** a LoggerProvider is set as the global OTel logger provider
+- **AND** the Python root logger has a LoggingHandler attached
+
+#### Scenario: Resource attributes set on all providers
+- **GIVEN** `APP_VERSION=1.2.3` and `APP_ENVIRONMENT=production`
+- **WHEN** `telemetry.init("payments-api")` is called
+- **THEN** all providers share a Resource with:
+  - `service.name = "payments-api"`
+  - `service.version = "1.2.3"`
+  - `deployment.environment = "production"`
+
+#### Scenario: OTEL_SERVICE_NAME overrides argument
+- **GIVEN** `OTEL_SERVICE_NAME=env-override` is set
+- **WHEN** `telemetry.init("code-name")` is called
+- **THEN** `service.name` in the Resource is `"env-override"`
+
+#### Scenario: Init is idempotent
+- **GIVEN** `telemetry.init("svc")` was already called
+- **WHEN** `telemetry.init("svc")` is called again
+- **THEN** providers are not re-created or re-registered
+- **AND** no error is raised
+
+### Requirement: Graceful Shutdown
+The library SHALL expose `telemetry.shutdown()` that flushes all pending
+signals before the process exits.
+
+#### Scenario: Shutdown flushes pending signals
+- **GIVEN** `telemetry.init("svc")` was called and signals are buffered
+- **WHEN** `telemetry.shutdown()` is called
+- **THEN** all three providers are shut down in order (traces, metrics, logs)
+- **AND** pending signals are flushed to the exporter
+- **AND** no error is raised if the exporter is unreachable (logged at WARN)
+
+#### Scenario: Shutdown before init is a no-op
+- **GIVEN** `telemetry.init()` was never called
+- **WHEN** `telemetry.shutdown()` is called
+- **THEN** no exception is raised

carros_ai_utils-0.2.0/openspec/changes/archive/2026-04-03-init-telemetry-python/specs/logger/spec.md

@@ -0,0 +1,50 @@
+## Purpose
+Bridge the Python standard logging module to OpenTelemetry so that all
+existing logging.getLogger() calls are automatically exported via OTLP,
+with no changes required in application code.
+
+### Requirement: Logging Bridge via LoggingHandler
+After `telemetry.init()`, the library SHALL attach an OTel LoggingHandler to
+the Python root logger so all log records at WARNING level and above are
+exported via OTLP.
+
+#### Scenario: Existing logger sends to OTLP after init
+- **GIVEN** `telemetry.init("svc")` was called
+- **AND** a logger exists: `logger = logging.getLogger("mymodule")`
+- **WHEN** `logger.warning("something failed")`
+- **THEN** a log record is emitted to the OTel LoggerProvider
+- **AND** no changes to the existing logger code are required
+
+#### Scenario: Log level threshold is WARNING
+- **GIVEN** `telemetry.init("svc")` was called
+- **WHEN** `logger.debug("debug message")` is called
+- **THEN** the debug record is NOT exported via OTLP
+- **AND** it MAY still appear in stdout depending on the app's log config
+
+#### Scenario: Log record carries trace context
+- **GIVEN** a span is active when a log is emitted
+- **WHEN** `logger.error("payment failed")`
+- **THEN** the exported log record includes `trace_id` and `span_id`
+  matching the active span
+- **AND** the log is correlated with the trace in HyperDX
+
+### Requirement: No Disruption to Existing Log Handlers
+Attaching the OTel LoggingHandler SHALL NOT remove or replace existing
+handlers on the root logger.
+
+#### Scenario: Existing stdout handler preserved
+- **GIVEN** the application has a StreamHandler on the root logger before init()
+- **WHEN** `telemetry.init("svc")` is called
+- **THEN** the StreamHandler is still present and active
+- **AND** logs still appear in stdout as before
+- **AND** logs are also exported via OTLP
+
+### Requirement: Stdout Logging in Development
+When not in production mode, the library SHALL NOT attach the OTel
+LoggingHandler — logs remain in stdout only.
+
+#### Scenario: No OTLP logging handler in development
+- **GIVEN** `APP_ENVIRONMENT` is not set
+- **WHEN** `telemetry.init("svc")` is called
+- **THEN** no OTel LoggingHandler is added to the root logger
+- **AND** logging behavior is unchanged from default Python behavior

carros_ai_utils-0.2.0/openspec/changes/archive/2026-04-03-init-telemetry-python/specs/meter/spec.md

@@ -0,0 +1,38 @@
+## Purpose
+Provide convenient access to a pre-configured Meter for recording metrics
+(counters, histograms, gauges), without requiring direct interaction with
+the MeterProvider.
+
+### Requirement: Meter Access
+The library SHALL expose `telemetry.meter(name?)` that returns an OTel Meter
+scoped to the given name, defaulting to the service name from init().
+
+#### Scenario: Meter returned after init
+- **GIVEN** `telemetry.init("payments-api")` was called
+- **WHEN** `meter = telemetry.meter()` is called
+- **THEN** a valid `opentelemetry.metrics.Meter` instance is returned
+
+#### Scenario: Counter creation and recording
+- **GIVEN** a valid Meter instance
+- **WHEN** `counter = meter.create_counter("requests_total")` and `counter.add(1)`
+- **THEN** the counter value is buffered for export
+
+#### Scenario: Histogram creation and recording
+- **GIVEN** a valid Meter instance
+- **WHEN** `hist = meter.create_histogram("request_duration_ms")` and `hist.record(42.5)`
+- **THEN** the observation is buffered for export
+
+#### Scenario: Meter before init returns no-op
+- **GIVEN** `telemetry.init()` was never called
+- **WHEN** `telemetry.meter()` is called
+- **THEN** a no-op Meter is returned
+- **AND** no exception is raised
+
+### Requirement: Metric Export Interval
+Metrics SHALL be exported on a periodic basis using the OTLP periodic
+exporting MetricReader with a default interval of 60 seconds.
+
+#### Scenario: Default export interval applied
+- **GIVEN** no custom interval is configured
+- **WHEN** the MeterProvider is initialized
+- **THEN** a PeriodicExportingMetricReader with `export_interval_millis=60000` is used

carros_ai_utils-0.2.0/openspec/changes/archive/2026-04-03-init-telemetry-python/specs/otlp-exporter/spec.md

@@ -0,0 +1,45 @@
+## Purpose
+Configure OTLP gRPC exporters for traces, metrics, and logs that point to
+the telemetry-collector, or fall back to stdout exporters for local development.
+
+### Requirement: gRPC Exporters in Production
+When `config.is_production` is True, the library SHALL create OTLP gRPC
+exporters for all three signal types using the configured endpoint.
+
+#### Scenario: Trace exporter created for production
+- **GIVEN** `APP_ENVIRONMENT=production` and `OTEL_EXPORTER_OTLP_ENDPOINT=collector:4317`
+- **WHEN** the trace exporter is built
+- **THEN** it is an `OTLPSpanExporter` configured with `endpoint="collector:4317"`
+- **AND** it uses insecure credentials (no TLS — private network)
+
+#### Scenario: Metrics exporter created for production
+- **GIVEN** `APP_ENVIRONMENT=production`
+- **WHEN** the metrics exporter is built
+- **THEN** it is an `OTLPMetricExporter` configured with the same endpoint
+
+#### Scenario: Logs exporter created for production
+- **GIVEN** `APP_ENVIRONMENT=production`
+- **WHEN** the logs exporter is built
+- **THEN** it is an `OTLPLogExporter` configured with the same endpoint
+
+### Requirement: Stdout Exporters in Development
+When `config.is_production` is False, the library SHALL use console/stdout
+exporters so developers can inspect signals locally without a collector.
+
+#### Scenario: Console exporters used in development
+- **GIVEN** `APP_ENVIRONMENT` is not set (defaults to development)
+- **WHEN** exporters are built
+- **THEN** traces use `ConsoleSpanExporter`
+- **AND** metrics use `ConsoleMetricExporter`
+- **AND** logs use `ConsoleLogExporter`
+- **AND** no network connection is attempted
+
+### Requirement: Insecure gRPC Connection
+The OTLP gRPC exporters SHALL connect without TLS when targeting the
+telemetry-collector on the private Docker network.
+
+#### Scenario: Insecure credentials used
+- **GIVEN** `APP_ENVIRONMENT=production`
+- **WHEN** the gRPC exporter is initialized
+- **THEN** it passes `insecure=True` (or equivalent credential config)
+- **AND** no certificate files are required

carros_ai_utils-0.2.0/openspec/changes/archive/2026-04-03-init-telemetry-python/specs/tracer/spec.md

@@ -0,0 +1,34 @@
+## Purpose
+Provide convenient access to a pre-configured Tracer for creating spans,
+without requiring application code to interact with the TracerProvider directly.
+
+### Requirement: Tracer Access
+The library SHALL expose `telemetry.tracer(name?)` that returns an OTel Tracer
+scoped to the given name, defaulting to the service name from init().
+
+#### Scenario: Tracer returned after init
+- **GIVEN** `telemetry.init("payments-api")` was called
+- **WHEN** `tracer = telemetry.tracer()` is called
+- **THEN** a valid `opentelemetry.trace.Tracer` instance is returned
+- **AND** it can create spans via `tracer.start_as_current_span("op")`
+
+#### Scenario: Named tracer for library scoping
+- **GIVEN** `telemetry.init("payments-api")` was called
+- **WHEN** `tracer = telemetry.tracer("payments.checkout")` is called
+- **THEN** the returned tracer is scoped to `"payments.checkout"`
+
+#### Scenario: Tracer before init returns no-op
+- **GIVEN** `telemetry.init()` was never called
+- **WHEN** `telemetry.tracer()` is called
+- **THEN** a no-op Tracer is returned (spans are created but not exported)
+- **AND** no exception is raised
+
+### Requirement: Span Context Propagation
+Tracers created via `telemetry.tracer()` SHALL propagate context automatically
+via the W3C TraceContext standard.
+
+#### Scenario: Child span linked to parent
+- **GIVEN** a parent span is active
+- **WHEN** a new span is started via `tracer.start_as_current_span("child")`
+- **THEN** the child span carries the same `trace_id` as the parent
+- **AND** its `parent_span_id` equals the parent span's `span_id`