Configuration

Configure the Risicare SDK for your application.

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

JavaScript SDK?

For JavaScript/TypeScript configuration, see the JS Configuration guide.

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
)

API Key = Project

Your API key is scoped to the project it was created under (visible in Settings → General). No separate project_id is needed — the gateway resolves it from your key.

project_id is deprecated

Passing project_id to init() emits a DeprecationWarning in Python (or console.warn in JavaScript). The parameter is ignored by the gateway and will be removed in v1.0. Use service_name and environment for within-project organization instead.

Configuration Options

Required

Option	Type	Description
`api_key`	`str`	Your Risicare API key. Starts with `rsk-`. Each key is scoped to one project.

Optional

Option	Type	Default	Description
`endpoint`	`str`	`"https://app.risicare.ai"`	Gateway endpoint URL
`environment`	`str`	`"development"`	Environment name (development, staging, production)
`service_name`	`str`	`None`	Service name for within-project organization
`service_version`	`str`	`None`	Service version for traces
`enabled`	`bool`	`True`	Enable/disable tracing globally
`trace_content`	`bool`	`True`	Capture prompt/completion content
`sample_rate`	`float`	`1.0`	Sampling rate (0.0-1.0, clamped)
`batch_size`	`int`	`100`	Spans per batch export (clamped to 1–10,000)
`batch_timeout_ms`	`int`	`1000`	Milliseconds between batch exports
`auto_patch`	`bool`	`True`	Patch `ThreadPoolExecutor`, `ProcessPoolExecutor`, and `asyncio.create_task` for automatic context propagation
`debug`	`bool`	`False`	Enable debug logging (see detail below)
`exporters`	`list[SpanExporter]`	`None`	Custom span exporters (default: HTTP exporter when `api_key` is provided)
`metadata`	`dict`	`{}`	Global metadata attached to all spans
`otlp_endpoint`	`str`	`None`	OTLP/HTTP export endpoint
`otlp_headers`	`dict`	`None`	OTLP export headers
`otel_bridge`	`bool`	`False`	Enable OpenTelemetry bridge

Content truncation

When trace_content=True, captured prompt and completion text is truncated to 10,000 characters per field. Content exceeding this limit is cut with a "... [truncated]" marker. This limit is not configurable — it's a hardcoded safety bound to prevent oversized spans.

auto_patch monkey-patches at import time

When auto_patch=True (default), init() monkey-patches all detected LLM provider libraries (OpenAI, Anthropic, etc.) via import hooks. For precise control over which providers are instrumented, set auto_patch=False and call instrument_already_imported() or install_import_hooks() selectively.

What `debug=True` enables

Console exporter: Adds a ConsoleExporter that prints every span to stderr as it's exported
Orphan trace warnings: Logs a warning when an LLM call has no parent span (each call becomes its own trace — a common Tier 1 mistake)
Initialization logging: Reports patching status (ThreadPoolExecutor, asyncio.create_task), endpoint, and service name on startup
HTTP export errors: Logs failed export requests, timeouts, and non-2xx responses (normally silent)

Environment Variables

All configuration can be set via environment variables:

export RISICARE_API_KEY="rsk-..."
export RISICARE_ENDPOINT="https://app.risicare.ai"
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_NAME="my-service"
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"

Variable	Maps To
`RISICARE_API_KEY`	`api_key`
`RISICARE_ENDPOINT`	`endpoint`
`RISICARE_ENVIRONMENT`	`environment`
`RISICARE_SERVICE_NAME`	`service_name`
`RISICARE_SERVICE_VERSION`	`service_version`
`RISICARE_TRACING`	`enabled`
`RISICARE_TRACE_CONTENT`	`trace_content`
`RISICARE_SAMPLE_RATE`	`sample_rate`
`RISICARE_DEBUG`	`debug`
`RISICARE_OTLP_ENDPOINT`	`otlp_endpoint`
`RISICARE_OTLP_HEADERS`	`otlp_headers`
`RISICARE_OTEL_BRIDGE`	`otel_bridge`

Zero-Code Instrumentation

Set RISICARE_TRACING=true to enable auto-instrumentation without any code changes.

Advanced Configuration

Custom Endpoint

For self-hosted deployments:

risicare.init(
    api_key="rsk-...",
    endpoint="https://your-risicare-instance.com",
)

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")

Flush Pending Spans

# Force export all pending spans
client = risicare.get_client()
client.flush()

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

Shutdown may block on network issues

If the exporter is mid-request when shutdown() runs, the thread join blocks for up to timeout_ms. In latency-sensitive paths, reduce the timeout: risicare.shutdown(timeout_ms=1000).

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
get_instrumented_modules()
# {'openai', 'anthropic'}
 
# Check a specific library
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()