# Configuration

> Common SDK and OpenTelemetry settings, defaults, and production guidance.

Canonical page: https://anectico.com/docs/reference/configuration/


Prefer environment variables for credentials and deployment-specific values. Use SDK options for
settings that are part of application behavior.

## Common settings

| Setting | Environment variable | Typical value |
| --- | --- | --- |
| API key | `ANECTICO_API_KEY` | `an_...` |
| Service name | `OTEL_SERVICE_NAME` | `orders-api` |
| Service version | `OTEL_SERVICE_VERSION` | release tag or commit SHA |
| Environment | `ANECTICO_ENVIRONMENT` | `production`, `staging`, `development` |
| Endpoint | `ANECTICO_ENDPOINT` | `https://api.anectico.com` |
| OpenTelemetry ownership (JavaScript/Python) | `ANECTICO_OTEL_MODE` | `managed` or `existing` |
| Debug output | `ANECTICO_DEBUG` | `false` in normal production use |
| Python log redaction additions | `ANECTICO_LOG_REDACTION_FIELDS` | comma-separated application field names |

The JavaScript, Python, and Go SDKs also accept these values through their constructors or options.

Use `ANECTICO_OTEL_MODE=existing` in JavaScript or Python only when the application
already registers and owns its OpenTelemetry providers, exporters,
instrumentation, and lifecycle. Anectico helpers then use those globals without
creating, flushing, or shutting them down. Configure the application exporter
or Collector destination and API-key header separately.

Python validates every enabled signal's resolved endpoint before constructing
an exporter. HTTP requires an absolute `http(s)` URL. Python gRPC accepts an
`http(s)` authority URL without a path or a `host:port` target. The standard
signal-specific `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`,
`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`, and
`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` overrides remain supported.

## Service naming

Use the same stable `service.name` for every instance of one deployable application. Put pod, host,
or instance identity in resource attributes rather than changing the service name.

Set a version on every deploy. This is required for reliable release comparison and symbolication.

## Environments

Use a small consistent set such as `production`, `staging`, and `development`. `prod` and
`production` are different values and create separate views.

## Sampling

Begin with default sampling. Increase it temporarily when validating setup or reproducing a rare
problem. Errors should remain captured even when ordinary trace sampling is reduced.

The managed Go tracer provider preserves the sampled or unsampled decision from local and remote
parents and applies `WithTraceSampleRate` only to new root traces. Explicit captured errors and
messages remain retained. A Go application that supplies `WithTracerProvider` owns its sampler and
Anectico does not change it.

Sampling decisions affect the evidence available to customer timelines and Customer Detective. Do
not lower sampling before measuring whether critical journeys still retain enough connected traces.

## Batching and shutdown

Defaults are suitable for most applications. Tune batch size, queue size, and export timeout only
after observing memory or delivery problems. Short-lived jobs must flush or stop the SDK before the
process exits.

Python `AnecticoClient.stop()` returns a `ShutdownResult`; check `success` rather
than treating hook ownership as delivery. In managed mode, enabled providers
flush and shut down concurrently within one aggregate deadline. In existing
mode, `stop()` returns an unattempted result and `flush()` returns `False`; the
application lifecycle must flush/shut down its providers. HTTP certificate verification,
TLS configuration, and client-certificate failures fail after one request with
a sanitized diagnostic. Transient connection loss and retryable `408`/`5xx`
responses retain the same serialized batch through the configured HTTP export
timeout, with deadline-bounded backoff and no nested retry loop. Shutdown
interrupts the retry window. Certificate verification is never disabled
automatically.

## Secrets

- Store API keys in your deployment secret manager.
- The Python standard-library logging bridge redacts common credential and financial-account fields
  before export. Use `ANECTICO_LOG_REDACTION_FIELDS` only to add application-specific field names; it
  does not replace the built-in protection.
- Use a project-scoped key with `ingest:write` for OTLP telemetry and errors.
- Add `analytics:write` when the SDK calls identify, group, screen, or diagnostic-event methods.
- Add `replay:write` only to browser integrations that record session replay.
- Never ship management, MCP-write, administrator, or unrelated read scopes in browser or mobile
  builds. Client-side flag evaluation is the explicit exception: it needs `flags:read`, so flag
  configuration and payloads must contain no secrets.
- Rotate keys independently by application and environment.

## Debugging

Enable SDK debug output only while troubleshooting. It can be verbose and should not become part of
normal application logging. After changing configuration, follow [Verify your setup](/docs/start/verify-setup).