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 and 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.

Go and Python validate each enabled, SDK-owned HTTP export destination before constructing an exporter. HTTP requires an absolute http(s) URL without embedded credentials, query, or fragment. Invalid explicit URLs fail instead of falling back to an ambient destination; errors do not echo the URL. Python gRPC accepts an http(s) authority URL without a path or a host:port target. The standard signal-specific endpoint variables remain supported as defaults.

Go and Python resolve endpoint settings once when configuration is created. For each enabled signal, precedence is:

1. An explicit signal endpoint: Go WithTracesEndpoint, WithMetricsEndpoint, or WithLogsEndpoint (or the corresponding Config field); Python traces_endpoint, metrics_endpoint, or logs_endpoint.
2. An explicit client base endpoint: Go WithEndpoint or an explicit Config; Python endpoint or an explicit AnecticoConfig.
3. OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, or OTEL_EXPORTER_OTLP_LOGS_ENDPOINT from the configuration's environment snapshot.
4. ANECTICO_ENDPOINT, then https://api.anectico.com.

Explicit signal endpoints remain in effect regardless of the order of Go's base and signal options. HTTP signal endpoints are complete URLs, including the signal path; the SDK appends /v1/traces, /v1/metrics, or /v1/logs only to a base endpoint. gRPC uses an authority without a signal path. Changing environment variables does not redirect an existing configuration; create a new client to pick up deployment changes. In existing OpenTelemetry mode, the application owns exporter destinations.

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 to your agent. 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 and 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.