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.