Configuration

Configure the Risicare SDK to connect to your project and customize tracing behavior.

Basic Setup

import risicare
 
risicare.init(
    api_key="rsk-...",              # Or use RISICARE_API_KEY env var
    service_name="my-agent",        # Identify your service
    environment="production",       # Environment name
)

Configuration Options

Required

Optional

What debug=True enables

• Console exporter: Adds a ConsoleExporter that prints every span to stdout as it's exported — including span attributes. With no API key it still prints the spans, but they are not counted as exported and not delivered, and flush() returns False
• Debug log messages: Messages about an LLM call with no parent span (each such call becomes its own trace — a common Tier 1 mistake) and about initialization go to the risicare logger at DEBUG level. You see them only if you set that logger to DEBUG
• No startup line: The [risicare] Tracing active line is not printed when debug=True

import logging
logging.getLogger("risicare").setLevel(logging.DEBUG)

Span Delivery

When you pass an api_key, init() installs the HTTP exporter. This is the default path — if you have not configured exporters or an OTLP endpoint, this is what is sending your spans.

Environment Variables

You can set these options with environment variables:

export RISICARE_API_KEY="rsk-..."
export RISICARE_ENVIRONMENT="production"
export RISICARE_SERVICE_NAME="my-agent"
export RISICARE_TRACING="true"
export RISICARE_TRACE_CONTENT="true"
export RISICARE_SAMPLE_RATE="1.0"
export RISICARE_SERVICE_VERSION="1.0.0"
export RISICARE_DEBUG="false"
export RISICARE_OTLP_ENDPOINT="https://otel-collector:4318"
export RISICARE_OTLP_HEADERS="key1=value1,key2=value2"
export RISICARE_OTEL_BRIDGE="false"

risicare.init() reads these fifteen variables. The import hooks read one more, RISICARE_STRICT_INSTRUMENTATION — see Production & Failure Modes. batch_size, batch_timeout_ms, auto_patch, exporters, metadata and mask have no environment variable.

Boolean variables accept true, 1, yes and on, in upper or lower case. Any other value, including an empty value, means false. RISICARE_TRACING has its own rule: the value is trimmed and case is ignored; true, 1, yes and on turn tracing on; false, 0, no and off turn it off; an empty value is the same as no value; any other value turns tracing off and logs one WARNING.

Advanced Configuration

Custom Endpoint

Override the default gateway endpoint (https://ingest.risicare.ai) — for example, to send spans through an outbound proxy your network requires:

risicare.init(
    api_key="rsk-...",
    endpoint="https://llm-egress-proxy.internal.example.com",
)

endpoint sets where the SDK sends spans. If you do not also pass api_endpoint, the SDK sends scores to the same host as endpoint. To send scores to a different host, pass api_endpoint: when endpoint is passed as an option, RISICARE_API_ENDPOINT does not override it.

Sampling

Control trace sampling rate:

risicare.init(
    api_key="rsk-...",
    sample_rate=0.1,  # Sample 10% of traces
)

Programmatic Control

Check Status

if risicare.is_enabled():
    print("Tracing is active")

is_enabled() is False before init(), with tracing off, with no API key (and no exporter of your own), and after the SDK's own SIGTERM drain.

Flush Pending Spans

# Send the spans queued so far. The SDK stays usable afterwards.
risicare.flush(timeout_ms=5000)  # default: 5000ms

flush() returns a bool. True means that the gateway (in Python, also an exporter that you named) acknowledged every span and every score that the SDK accepted since the previous flush() returned, and that nothing is in the queue or in flight. This holds also in a signal handler and after shutdown().

A loss (a span dropped, rejected or not acknowledged, or a score that failed) makes the next flush() return False one time, and the one after it True again. flush() also returns False before init(), with tracing off, and with no API key (and no exporter of your own).

With more than one exporter, a batch counts as delivered when the first exporter that succeeds takes it, so True means that at least one exporter acknowledged each span; a failure of another exporter shows only in its own WARNING and in failed_exports. A span that you start after shutdown() has returned is not made, and nothing counts it.

When it is False, read risicare.get_metrics(): dropped_spans_by_reason, rejected_spans and failed_scores name the loss; a False at the deadline with none of them raised means that the spans are still in flight. See the flush() reference for every case.

metrics = risicare.get_metrics()
print(metrics["exported_spans"], metrics["failed_exports"], metrics["dropped_spans"])

See the Python SDK reference for every field.

Shutdown

# Graceful shutdown - flushes and closes connections
risicare.shutdown(timeout_ms=5000)  # default: 5000ms

shutdown() waits up to timeout_ms for the batch processor thread to drain, then performs a final flush and closes HTTP connections. An atexit handler calls shutdown() automatically on normal exit — explicit calls are only needed when you want to flush mid-process (e.g., serverless functions, before a long non-tracing phase).

Auto-Instrumentation Management

Control which libraries are automatically instrumented:

from risicare import (
    install_import_hooks,
    remove_import_hooks,
    instrument_already_imported,
    is_instrumented,
    get_instrumented_modules,
    get_supported_modules,
)
 
# See which libraries can be auto-instrumented
get_supported_modules()
# {'openai', 'anthropic', 'cohere', 'google.generativeai', 'mistralai', ...}
 
# Check what's currently instrumented — returns a per-module state record
get_instrumented_modules()
# {'openai':    {'state': 'instrumented', 'hooks_landed': 4, ...},
#  'anthropic': {'state': 'instrumented', 'hooks_landed': 2, ...}}
# A patched provider reports "instrumented"; "failed" if its patch raised;
# "pending" if the module that holds its patch points is not imported yet.
 
# Check a specific library: True when at least one hook landed.
is_instrumented("openai")  # True
 
# Instrument libraries that were imported before risicare.init()
count = instrument_already_imported()
# Returns number of newly instrumented modules
 
# Remove all import hooks (stops future auto-instrumentation)
remove_import_hooks()
 
# Re-install import hooks
install_import_hooks()

Configuration Precedence

Configuration is resolved in this order (highest to lowest priority):

1. Explicit init() parameters
2. Environment variables
3. Default values

Next Steps