Acceldata
AIO

Last updated: Oct 07, 2026 16:30 UTC

This page lists the public functions, decorators, classes, and settings of the AIO Python SDK, with their parameters, defaults, and the messages they produce.

Package

Item Value
Package name acceldata-aio-tracer
Import name acceldata_aio_tracer
Version 1.1.3
Python >=3.10,<4.0
Optional extras http, which adds the FastAPI and httpx instrumentations, and db, which adds the OpenTelemetry instrumentations for dbapi, psycopg2, pymysql, mysql, asyncpg, aiopg, mysqlclient, and pymssql. psycopg (v3) support is built in and needs neither extra.
Console script aio-instrument. For its options, see CLI.

For installation and a first trace, see Instrument your code.

init

init(service=None, tenant_id=None, project_id=None, endpoint=None, *,
     aio_collector_endpoint=None, project_name=None, access_key=None,
     secret_key=None, environment=None, instrument=True,
     redaction=None, data_source_hosts=None) -> bool

Starts telemetry. Call it once, before you construct any HTTP or model client. You must give a nonblank tenant id and exactly one of project_id or project_name.

import acceldata_aio_tracer

enabled = acceldata_aio_tracer.init(
    service="support-bot",
    tenant_id="acme",
    project_name="Support bot",
    endpoint="https://aio.example.com",
    access_key="EXAMPLE_ACCESS_KEY",
    secret_key="EXAMPLE_SECRET_KEY",
    environment="staging",
)
print("AIO telemetry enabled:", enabled)

Replace the tenant, project, endpoint, and keys with your own values. To get a key, see Create an API key.

Parameters

Parameter Meaning Environment fallback, in order Default
service Application name, set as service.name OTEL_SERVICE_NAME unknown_service
tenant_id Tenant aio.tenant_id in OTEL_RESOURCE_ATTRIBUTES, then AIO_TENANT_ID None. Required.
project_id Project id aio.project_id in OTEL_RESOURCE_ATTRIBUTES, then AIO_PROJECT_ID None
project_name Project, found by its exact name None. Pass it as an argument only. None
endpoint AIO server URL AIO_ENDPOINT None
aio_collector_endpoint OTLP/HTTP collector base URL AIO_COLLECTOR_ENDPOINT, then OTEL_EXPORTER_OTLP_ENDPOINT, then the resolved endpoint None
access_key Gateway access key AIO_ACCESS_KEY None
secret_key Gateway secret key AIO_SECRET_KEY None
environment Deployment environment, set as deployment.environment deployment.environment in OTEL_RESOURCE_ATTRIBUTES, then AIO_ENVIRONMENT default
instrument Wrap supported libraries so they create spans automatically. Pass False to set up the SDK without wrapping any library. None True
redaction A redaction policy built with redaction_policy The AIO_HIDE_* and AIO_REDACT_* variables, used only when this is None None
data_source_hosts A map from the address your application connects to, to the address the catalog has the data source registered under. See Data source hosts. AIO_DATA_SOURCE_HOSTS, in the form from=to,from=to, used only when this is None None
  • Arguments win over environment variables.
  • Values in OTEL_RESOURCE_ATTRIBUTES are URL-unquoted.
  • The access key and secret key are sent with every export only when both are set.
  • service, tenant_id, project_id, and endpoint won't be renamed. The keyword-only parameters may change in later versions.
  • Integrations for libraries that aren't installed are skipped.
  • instrument=False stops library wrapping only. The SDK's own configuration, which @trace, the guards, and the helpers read, is still set up.
  • Content capture, which records prompt, response, and message content on spans, is on by default. To turn it off, set OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false. When it's off, the literal values in SQL statements on database spans are withheld too.

Important: Since version 1.0.0.dev2, endpoint means the AIO server. Before that, it meant the OTLP collector. If you upgrade from an earlier version, move your collector URL to aio_collector_endpoint.

Return value

init returns True when telemetry is enabled and False when it isn't. It never raises, except RedactionUnavailable. A second call returns True and does nothing.

Project by name

When you pass project_name, the SDK asks the AIO server at endpoint for its projects and picks the one whose name matches exactly.

  • If no project matches, the SDK creates one with the description "Auto created by SDK", the "Acceldata hosted" storage mode, and 60 retention days. For retention, see Data retention.
  • If another process creates the same project at the same moment, the SDK lists the projects once more.
  • The lookup times out after 3.05 seconds to connect and 10.0 seconds to read.

A project_id that you pass is used as is, without any check against the server.

Data source hosts

Use data_source_hosts when your application reaches a database by an address the catalog doesn't know, such as localhost through a tunnel or a private-link alias. The SDK writes the mapped address as aio.data.source.address and aio.data.source.port, next to the driver's own address and never over it.

import acceldata_aio_tracer

acceldata_aio_tracer.init(
    tenant_id="acme",
    project_id="0190f3a2-7c1e-7b8a-9d2f-1a2b3c4d5e6f",
    data_source_hosts={"localhost:5432": "orders-db.acme.com:5432"},
)
  • A key is host:port, or host alone to match every port. The more specific key wins.
  • A value is host:port, or host alone to keep the original port.
  • Keys are lower-cased. A pair with a blank side is dropped, not rejected.
  • The map is matched against the span's server.address (or net.peer.name) and server.port (or net.peer.port).

For how this links queries to catalog assets, see Record the data your agent uses.

Export

  • Spans are exported in batches. The span queue holds 10,000 spans unless OTEL_BSP_MAX_QUEUE_SIZE is set. The batch size is OpenTelemetry's default of 512.
  • Every signal is gzip-compressed unless OTEL_EXPORTER_OTLP_<SIGNAL>_COMPRESSION or OTEL_EXPORTER_OTLP_COMPRESSION is set.

Messages

init logs these messages when it can't start telemetry. In each case it returns False.

Situation Message
Tenant id is blank "aio: nonblank tenant_id is required; telemetry is disabled"
Neither or both project selectors are given "aio: exactly one nonblank project_id or project_name is required; telemetry is disabled"
The project can't be resolved "aio: project resolution failed (failed to list projects: HTTP 401); continuing without telemetry"
Setup fails "aio: telemetry setup failed; continuing without it"

On success, init logs an info message that names the service, tenant, project, contract revision, and instrumentation setting.

When project resolution fails, the reason in parentheses is one of the following:

  • "exactly one nonblank project_id or project_name is required"
  • "endpoint is required when project_name is used"
  • "failed to list projects: Read timed out."
  • "failed to list projects: HTTP 503"
  • "malformed list projects response"
  • "duplicate exact project name"
  • "failed to create project: Read timed out."
  • "failed to create project: HTTP 403"
  • "malformed create project response"
  • "project 'Support bot' is still absent after create conflict"
  • "project must contain a nonblank id"

These reasons come from ProjectResolutionError, a subclass of RuntimeError.

If your application already set up OpenTelemetry

  • An existing OpenTelemetry SDK TracerProvider is reused as is. If its resource doesn't carry the AIO tenant and project, the SDK warns you, and the telemetry lands under the default tenant. To avoid this, add aio.tenant_id and aio.project_id to that provider's resource, or call init before you configure OpenTelemetry.
  • An existing LoggerProvider must have an empty synchronous processor pipeline. Otherwise the error is "aio: reused LoggerProvider must have an empty synchronous processor pipeline so attribution runs before export". A logger provider that the SDK can't attach to gives "aio: existing logger provider is not an attachable SDK LoggerProvider".
  • If redaction is configured and a TracerProvider already exists, init raises RedactionUnavailable.
  • When a TracerProvider is reused, entering a redact_model_inputs scope warns once that span content can't be withheld. Log records are still covered. Call init before you configure OpenTelemetry to avoid this.

For sending data from your own OpenTelemetry pipeline, see OpenTelemetry.

root_span

root_span(conversation_id: str, *, tenant_id=None, project_id=None, user_id=None,
          input_preview: str = "", name: str = "handle_message")

A context manager that opens the root span for one unit of work. Every span and log record created inside it gets the conversation id, user id, input preview, and identity.

import acceldata_aio_tracer

acceldata_aio_tracer.init(tenant_id="acme", project_id="0190f3a2-7c1e-7b8a-9d2f-1a2b3c4d5e6f")

question = "Where is my order?"
with acceldata_aio_tracer.root_span(
    "conv-123",
    user_id="user-42",
    input_preview=question,
) as span:
    print("Conversation:", acceldata_aio_tracer.current_conversation_id())
Parameter Meaning Default
conversation_id The session key, set as gen_ai.conversation.id Required
tenant_id Tenant for this operation None
project_id Project for this operation None
user_id The end user, set as aio.user_id None
input_preview The user input, set as aio.input_preview. Truncated to 2000 characters. Don't add a prefix such as "User query: ". ""
name Span name. Use a fixed, low-cardinality label. handle_message
  • It yields the span, or None if it couldn't start one.
  • Call it once per unit of work.
  • Its values overwrite matching attributes already on the spans inside it.
  • Nested root_span blocks restore the outer values when they exit.
  • It does nothing when init hasn't run.
  • It swallows its own failures and re-raises your application's exceptions.

current_conversation_id() -> str | None returns the conversation id of the open operation.

For how sessions group in the UI, see Track users and sessions.

Tags

A tag is a "key:value" string that labels spans. Tags set in code are stamped on spans as the attribute aio.tags, and on log records too. For the other ways to tag and for filtering by tags, see Tag traces.

import acceldata_aio_tracer as aio

aio.init(tenant_id="acme", project_id="0190f3a2-7c1e-7b8a-9d2f-1a2b3c4d5e6f")

aio.set_tags("team:support", "tier:gold")


@aio.using_tags("feature:refund")
def handle_refund():
    print("Tags:", aio.current_tags())


with aio.using_tags("channel:email"):
    handle_refund()
Function What it does
set_tags(*tags: str) -> None Replaces the tags in the current context. Every span and log record started afterward in that context carries them. Calling it with no tags clears them.
using_tags(*tags: str) Adds tags on top of the enclosing ones for a block, and restores the enclosing tags on exit. Use it as with aio.using_tags(...): or as a decorator on a sync or async function.
current_tags() -> tuple[str, ...] Returns the tags that a span started now would get
  • Tags are carried in a context variable, so asyncio tasks started inside a tagged block inherit them. There's no process-wide default.
  • Both the key and the value must be nonblank.
  • Validation never raises. Each tag that fails is logged and dropped, and duplicates are dropped silently.
Situation Message
The tag isn't a string "aio: tag 42 is not a string, dropped"
No colon, or an empty key or value "aio: tag 'team' must be 'key:value' with both sides nonblank, dropped"
The tag is longer than 200 characters "aio: tag 'note:…' exceeds 200 characters, dropped"
More than 32 tags "aio: 40 tags given, only the first 32 are kept (the server's own limit)"

Errors:

  • TypeError "using_tags() requires at least one tag"
  • TypeError "@using_tags cannot cover a generator; use with aio.using_tags(...): inside it"

declare_assets

declare_assets(*, reads=(), writes=())

Records which data the current span read or wrote. Call it inside a tool, retriever, or node. The references are stored on the span as the attribute aio.data.refs.declared.

import acceldata_aio_tracer as aio

aio.init(tenant_id="acme", project_id="0190f3a2-7c1e-7b8a-9d2f-1a2b3c4d5e6f")

with aio.root_span("conv-123"):
    aio.declare_assets(
        reads=[("snowflake://acme-prod", "SALES.PUBLIC.ORDERS")],
        writes=[
            {
                "namespace": "s3://acme-reports",
                "name": "daily/orders.csv",
                "kind": "file",
            }
        ],
    )

Each reference is either a (namespace, name) tuple or a dict. A dict has namespace and name, plus these optional keys:

Key Value
source_type The type of data source
kind table, view, file, endpoint, or collection
evidence Supporting detail for the reference
columns A list of the column or field names used. A bare string is ignored.
  • Each stored reference gets a direction of read or write, and the mechanism declare_assets.
  • Calling it again on the same span adds to the list. A repeated reference is stored once.
  • It does nothing when no recording span is open.
  • A reference with no namespace or no name makes the whole call record nothing.
  • Every failure is swallowed and logged as "aio: could not record declared assets".

For how references link to catalog assets, see Record the data your agent uses.

@langgraph_node

langgraph_node(func=None, *, input: Callable[[state], Any] | None = None,
               output: Callable[[state, result], Any] | None = None)

A decorator that records a LangGraph node's input and output. Used bare, it records the state the node received and the value it returned. Pass input(state) and output(state, result) to choose what's recorded instead. A helper that returns None leaves that side out.

from typing import TypedDict

from langgraph.graph import END, START, StateGraph

import acceldata_aio_tracer as aio

aio.init(tenant_id="acme", project_id="0190f3a2-7c1e-7b8a-9d2f-1a2b3c4d5e6f")


class State(TypedDict, total=False):
    question: str
    answer: str


@aio.langgraph_node(
    input=lambda state: state["question"],
    output=lambda state, result: result["answer"],
)
def answer(state: State) -> dict:
    return {"answer": f"You asked: {state['question']}"}


graph = StateGraph(State)
graph.add_node("answer", answer)
graph.add_edge(START, "answer")
graph.add_edge("answer", END)
app = graph.compile()
print(app.invoke({"question": "Where is my order?"}))
  • The content is sent as one gen_ai.agent.node.details log event on the node's invoke_agent <node> span. Input goes into gen_ai.input.messages with role user, and output into gen_ai.output.messages with role assistant.
  • Values that aren't strings are JSON-encoded. Each side is cut to 100,000 characters.
  • Attribution and redaction apply to the event.
  • When a node raises, its input is recorded and its output isn't.
  • Nothing is recorded when OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false, or when events are turned off.
  • The decorator marks the function and returns it unchanged.

Messages and errors:

  • A helper that isn't callable raises TypeError "@langgraph_node input= must be callable, got <class 'str'>".
  • A function that can't be marked logs "aio: @langgraph_node could not mark ; its input and output will not be recorded".
  • A helper that raises logs "aio: @langgraph_node output= helper raised; leaving it out".

Tracing helpers

@trace

A decorator that creates a CLIENT span named after the function, under the scope acceldata_aio_tracer. It sets gen_ai.output.messages, function.args, function.kwargs, service.name, and deployment.environment. When the function raises, the span gets ERROR status and records the exception, and the exception is re-raised.

Applying @trace to something that isn't callable raises TypeError "@trace can only be applied to callable objects, got <class 'str'>".

start_trace

start_trace(name) is a context manager that yields a TracedSpan. A TracedSpan has these methods:

  • set_result(result)
  • set_metadata(dict)

Context helpers

Function What it does
agent_context(name) Sets gen_ai.agent.name
agent_version_context(version) Sets gen_ai.agent.version. The SDK also sets acceldata_aio_tracer.agent.version_hash automatically.
using_attributes(attributes) Works as both a context manager and a decorator
inject_additional_attributes(fn, attributes) Takes a function and attributes

Agent metrics

log_agent_invocation(source, target, system=None) and log_agent_tool_error(agent_name, tool_name, system=None, model=None) record metrics. They swallow any errors.

Redaction

Redaction withholds content inside your application before it's sent. Every switch is off by default. For what each option does in practice, see the redaction overview.

redaction_policy

redaction_policy(*, hide_system_instructions=False, hide_tool_definitions=False,
                 redact_tool_arguments=(), redact_tool_results=(),
                 redact_attributes=(), suppress_spans=(),
                 redact_sql_literals=False, patterns=(), allow=None)

Builds a RedactionPolicy to pass to init as redaction=. It's also available as redaction.policy_from.

import acceldata_aio_tracer

acceldata_aio_tracer.init(
    tenant_id="acme",
    project_id="0190f3a2-7c1e-7b8a-9d2f-1a2b3c4d5e6f",
    redaction=acceldata_aio_tracer.redaction_policy(
        hide_system_instructions=True,
        redact_tool_arguments=["lookup_customer"],
        patterns=[r"\b\d{16}\b"],
    ),
)
Parameter Effect Details
hide_system_instructions Replaces system instructions with a digest Hide system prompts and tool definitions
hide_tool_definitions Replaces tool definitions with a digest Hide system prompts and tool definitions
redact_tool_arguments Digests the arguments of the named tools Redact tool arguments and results
redact_tool_results Digests the results of the named tools Redact tool arguments and results
redact_attributes Digests the named attributes on any span Drop attributes and spans
suppress_spans Leaves the named spans, and everything under them, out of the trace Drop attributes and spans
redact_sql_literals Removes literal values from SQL statements on database spans and keeps the statement SQL literals
patterns Replaces every regular expression match in message text and tool text with __REDACTED__ Redact by pattern
allow A function allow(match: str) -> bool that keeps a match when it returns True Redact by pattern
  • A digest is a sha256:<hex> value.
  • Tool lists accept a list or comma-separated values.
  • Patterns are compiled when the policy is built, so an invalid pattern fails at startup. Patterns can't be set from the environment.
  • RedactionPolicy is a frozen dataclass. Its .active property is true when any switch is set.
  • Redaction covers both spans and log records.
  • Message arrays that can't be parsed become __REDACTED__.
  • Redaction fails closed. If it fails, every content attribute becomes __REDACTED__, and the SDK logs "aio: redaction failed for span 'chat gpt-4o'; withholding its content" or "aio: redaction failed for a log record; withholding its content". The content attributes are the gen_ai message, system instruction, tool definition, and tool call attributes, plus db.query.text and db.statement. Timings, token counts, and identity are kept.

The redaction module also defines these constants:

Constant Value
REDACTED __REDACTED__
SYSTEM_INSTRUCTIONS gen_ai.system_instructions
INPUT_MESSAGES gen_ai.input.messages
OUTPUT_MESSAGES gen_ai.output.messages
TOOL_DEFINITIONS gen_ai.tool.definitions
TOOL_CALL_ARGUMENTS gen_ai.tool.call.arguments
TOOL_CALL_RESULT gen_ai.tool.call.result
TOOL_NAME gen_ai.tool.name
SCOPE_ATTRIBUTE aio.redaction.redact_model_inputs

SQL literals

With redact_sql_literals=True, values are removed from db.query.text and db.statement. The statement itself is kept, because the tables it names are what data references come from.

  • String literals become '?'. Numeric literals, including hex, become ?.
  • Postgres and Snowflake dollar-quoted bodies ($$…$$, $tag$…$tag$) become '?'.
  • Double-quoted text counts as a string literal only when db.system.name or db.system is mysql, mariadb, bigquery, databricks, spark, or hive. Everywhere else it's an identifier and is kept.
  • Comments (--, /* */), backtick identifiers, and digits that are part of a name or placeholder (t1, $1, :1, 2024_orders) are kept.
  • An unterminated string takes the rest of the statement with it.

When content capture is off, SQL literal redaction turns on automatically for spans, even if the policy doesn't set it.

Redaction environment variables

These variables apply only when init gets redaction=None.

Variable Effect
AIO_HIDE_SYSTEM_INSTRUCTIONS Flag. Only 1, true, yes, or on turns it on.
AIO_HIDE_TOOL_DEFINITIONS Flag. Only 1, true, yes, or on turns it on.
AIO_REDACT_TOOL_ARGUMENTS Comma-separated tool names
AIO_REDACT_TOOL_RESULTS Comma-separated tool names

redact_model_inputs

A decorator and context manager that digests model inputs for one part of your application. Use it as @aio.redact_model_inputs or @aio.redact_model_inputs() on a sync or async function, or as with aio.redact_model_inputs():.

  • Inside the scope, gen_ai.input.messages and gen_ai.system_instructions are replaced by a digest on spans and log records, but only for model calls (gen_ai.operation.name of chat or text_completion).
  • Output, and spans that aren't model calls, such as graph nodes and tools, are left alone.
  • It works with or without a redaction policy. When both act on the same keys, the scope wins.
  • Tasks started inside the scope inherit it.

Error: TypeError "@redact_model_inputs cannot cover a generator; use with aio.redact_model_inputs(): inside it".

@redact_arguments

redact_arguments(tool=None, *, name=None)

A decorator that digests the arguments of one tool. Apply it to a tool class or a function, or call it with only name=.

  • The tool name comes from, in order: the pydantic model_fields["name"].default, then .name, then __name__.
  • If no name is found, the SDK warns that it couldn't find a tool name and that nothing will be redacted for it. Pass name= to fix this.
  • It covers arguments only, never results.
  • Marked tools are added to redact_tool_arguments.
  • Import the tool before its spans are exported.

RedactionUnavailable

Raised by init when redaction is configured but your application already set up an OpenTelemetry TracerProvider. The message is "aio: redaction is configured, but this application already set up an OpenTelemetry TracerProvider. Redaction is applied by the span exporter, which that provider does not use, so span content would be exported unredacted. Call aio.init() before configuring OpenTelemetry."

Scores and threats

log_score

log_score(name, value, *, span=None, trace_id=None, span_id=None, comment=None,
          idempotency_key=None, metadata=None) -> bool

Attaches a gen_ai.evaluation.result event to a span, and also emits a log event unless events are turned off.

Parameter Recorded as
name gen_ai.evaluation.name
value A number becomes a float in gen_ai.evaluation.score.value. A bool becomes 1.0 or 0.0 and also sets the label "true" or "false". A string sets gen_ai.evaluation.score.label.
comment gen_ai.evaluation.explanation
idempotency_key acceldata_aio_tracer.score.idempotency_key
metadata Merged with the custom attributes. Only str, int, float, and bool values, or lists of them, are kept.

The score is attached to the first of these that's available:

  1. The span you pass.
  2. The current recording span.
  3. The span given by trace_id (32 hex characters) and span_id (16 hex characters).
  4. The current span.

Errors: "name is required", and TypeError "value must be numeric, boolean, or string". ValueError and TypeError are re-raised to you.

record_threat_detected

acceldata_aio_tracer.threat.record_threat_detected(rule_id, severity, threat_class, *,
                                                   span=None, **attributes) -> bool

Import it from acceldata_aio_tracer.threat. It isn't available at the top level.

  • It adds a gen_ai.agent.threat_detected event with gen_ai.agent.threat.rule_id, gen_ai.agent.threat.severity, and gen_ai.agent.threat.threat_class.
  • severity must be low, medium, high, or critical.
  • It returns False when no span is recording.

Errors: "rule_id is required", "severity must be one of: critical, high, medium, low", and "threat_class is required".

Guards

A guard is an in-process check on a prompt or a response. Guards run only when you call them through a Pipeline. For an introduction, see the Guard overview.

Pipeline

Pipeline(guards=None, fail_open=True).evaluate(text, phase="preflight")
  • phase is preflight, which checks the input before the model call, or postflight, which checks the output after it.
  • Actions, from least to most severe, are allow, warn, redact, and deny. The most severe action wins.
  • A deny stops the remaining guards. It doesn't raise anything by itself: read PipelineResult.action and decide what to do.
  • Redactions chain, so each guard sees the text the previous guard produced.
  • With fail_open=True, a guard that raises is treated as allow, and the pipeline logs a warning.
  • Each run emits a guard_requests metric and a guard.evaluation span event.

Results and errors

Name Contents
PipelineResult action, results, transformed_text. Its .explanation property joins the guards' explanations with "; ".
GuardResult action, score, guard_name, classification, explanation, transformed_text, latency_ms. .to_dict() returns guard.* keys.
GuardAction, GuardPhase Types for the action and phase values
GuardError Base guard error
GuardDeniedError(result) Error that carries a result
GuardTimeoutError Reserved
GuardConfigError Invalid guard configuration

Guard base class

Guard(action="deny", max_scan_length=102_400) is the base class for all guards. An invalid action raises GuardConfigError "Invalid action 'block'. Must be one of: allow, deny, redact, warn".

Built-in guards

Guard Arguments and defaults Phases Behavior
PII action="redact", custom_patterns as {label: regex} preflight, postflight 24 built-in patterns. Redaction writes [REDACTED:<label>]. Score is min(1, 0.5 + 0.2 × matches). The explanation gives the number of matches and their labels.
PromptInjection action="deny", threshold=0.5, classifier as Callable[[str], float], used only when no regular expression matches preflight The explanation gives the score and classification.
SensitiveTopic action="warn", categories, custom_categories, classifier that returns str or None preflight, postflight Categories are any of violence, politics, substance_use, mental_health, discrimination, and adult_content. Score is min(1, 0.4 + 0.3 × n).
TopicRestriction classifier (required), allowed or denied, action="deny" preflight Topics are matched in lowercase. Explanations look like "Topic 'politics' is not in the allowed list" or "Topic 'politics' is in the denied list".
Moderation action="warn", custom_words preflight, postflight Profanity scores 0.7, and toxicity scores 0.95. Redaction replaces profanity only, with [REDACTED:profanity]. Explanation example: "Moderation flag: profanity".
Schema action="deny", json_mode=False, schema=None postflight Invalid JSON gives classification invalid_json, score 1.0, and an explanation such as "Output is not valid JSON: Expecting value: line 1 column 1 (char 0)". A schema mismatch scores 0.9. The validator checks type, required, properties, and items.
Custom action="deny", pattern=None, callable=None, phases=None As given A pattern hit gives classification "pattern_match" and an explanation such as "Custom pattern matched: 'ORDER-1234'". Otherwise the callable's result is returned.

Configuration errors:

  • TopicRestriction: "TopicRestriction requires a callable 'classifier'", "Provide either 'allowed' or 'denied', not both", and "Provide either 'allowed' or 'denied' topic list".
  • Custom: "Custom guard needs at least 'pattern' or 'callable'".

Offline evaluations

Offline evaluations send a prompt and response pair to the AIO server, which scores it against eval types. For a walkthrough, see Run an eval.

eval

eval(prompt, response, contexts=None, eval_types=None, attributes=None,
     threshold_score=None, store_results=None, run_id=None, metadata=None,
     acceldata_aio_tracer_api_key=None, acceldata_aio_tracer_url=None,
     print_results=True) -> OfflineEvalResult
  • The API key comes from acceldata_aio_tracer_api_key, then AioConfig, then AIO_API_KEY. The URL comes from acceldata_aio_tracer_url, then AioConfig, then AIO_URL. A missing key or URL raises ValueError.
  • The request times out after 120 seconds. It's retried once on HTTP 429, on HTTP 5xx, and on a connection error.
  • Attributes are merged in this order, with later entries winning:
    1. OTEL_RESOURCE_ATTRIBUTES
    2. OTEL_SERVICE_NAME
    3. AIO_ENVIRONMENT or OTEL_DEPLOYMENT_ENVIRONMENT
    4. AioConfig
    5. The attributes you pass
  • With print_results=True, a summary is printed to stderr with the title "Acceldata AIO Offline Evaluation — PASSED" or "Acceldata AIO Offline Evaluation — FAILED".

Errors:

  • "Authentication failed. Check your Acceldata AIO API key."
  • "Server returned non-JSON response (HTTP 502)"
  • "Request timed out after 120s. The evaluation may still be running on the server."
  • "Cannot connect to Acceldata AIO server at https://aio.example.com: Connection refused"
  • "Evaluation failed after retries: HTTP 503"

eval_batch

eval_batch(dataset, eval_types=None, attributes=None, threshold_score=None,
           store_results=None, run_id=None, max_concurrent=5,
           print_results=True) -> BatchEvalResult
  • dataset is a non-empty list of dicts. Each dict has the string keys prompt and response, and can override contexts, eval_types, attributes, threshold_score, and metadata.
  • Items run in parallel, with up to max_concurrent at a time.
  • The default run_id is batch_ followed by 12 hex characters. It groups the evaluations of one batch.
  • The summary title is "Acceldata AIO Batch Evaluation — ALL PASSED" or, for example, "Acceldata AIO Batch Evaluation — 3 FAILED".

Errors:

  • "dataset must be a non-empty list of prompt/response dicts"
  • TypeError "dataset[2] must be a dict, got <class 'str'>"
  • "dataset[2] must have a 'prompt' string key"
  • "dataset[2] must have a 'response' string key"

get_eval_types

get_eval_types(acceldata_aio_tracer_api_key=None, acceldata_aio_tracer_url=None) returns a list of EvalType. It raises ValueError when authentication fails, ConnectionError, TimeoutError, or RuntimeError with a message that starts with "Failed to fetch eval types: ".

Result models

Model Fields and members
OfflineEvalResult success, evaluations, context_applied, metadata, error. .passed is true when success is true and no evaluation has the verdict "yes". Also has .failed_evals and .summary().
OfflineEvaluation type, score, verdict, classification, explanation
ContextInfo rule_matched, matching_rule_ids, context_entity_ids, user_contexts_count
BatchEvalResult results, run_id. Has .all_passed, .pass_rate, and .aggregate_summary().
EvalType id, label, description, enabled, is_custom, threshold_score

Prompts, secrets, and rule evaluation

These functions authenticate with a bearer token and time out after 120 seconds. The URL falls back to AIO_URL and the key to AIO_API_KEY. If either is missing, they raise RuntimeError "Missing Acceldata AIO URL: Provide as arg or set AIO_URL env var." or "Missing API key: Provide as arg or set AIO_API_KEY env var."

Function What it does On failure
get_prompt(url=None, name=None, api_key=None, prompt_id=None, version=None, should_compile=None, variables=None, meta_properties=None) Fetches a compiled prompt and returns the JSON Logs an error and returns None
get_secrets(url=None, api_key=None, key=None, tags=None, should_set_env=None) Fetches secrets. With should_set_env=True, also writes each returned secret to os.environ. Logs an error and returns None
evaluate_rule(url=None, api_key=None, entity_type=None, fields=None, include_entity_data=False, entity_inputs=None) Evaluates a rule. entity_type is "context", "prompt", or "evaluation". Logs an error and returns None

Configuration

resolve and build_resource

resolve and build_resource are available at the top level.

resolve(*, service, tenant_id, project_id, environment, endpoint,
        aio_collector_endpoint, access_key, secret_key, multi_tenant=False,
        redaction=None, data_source_hosts=None) -> Settings

resolve applies the same argument and environment precedence as init and returns a Settings object. Settings.otlp_headers() returns the headers sent with each export.

AioConfig

AioConfig is a single shared configuration object. Its defaults include:

Setting Default
environment "default"
application_name "default"
capture_message_content True
max_content_length None

When max_content_length is a positive integer, captured content is cut to that length and "..." is appended. A value of 0 or less, or a value that isn't an integer, means no truncation.

Instrumentor names

Instrumentor names, such as the ones you pass to --disabled_instrumentors in the CLI, are matched without regard to case. Aliases are resolved, for example "aiohttp" to "aiohttp-client" and "http" to "httpx". An invalid name logs "Invalid instrumentor name 'opneai'. Did you mean: openai?" or "Invalid instrumentor name detected and ignored: 'opneai'". For the libraries AIO works with, see Supported providers and frameworks.

The database driver names are psycopg, psycopg-pool, bigquery, psycopg2, pymysql, mysql, asyncpg, aiopg, mysqlclient, pymssql, and dbapi. The alias psycopg_pool resolves to psycopg-pool.

Environment variables

The SDK reads these variables. Arguments you pass in code win over them.

Variable Used for
OTEL_SERVICE_NAME service in init
OTEL_RESOURCE_ATTRIBUTES aio.tenant_id, aio.project_id, and deployment.environment in init. Also merged into offline evaluation attributes.
AIO_TENANT_ID tenant_id in init
AIO_PROJECT_ID project_id in init
AIO_ENDPOINT endpoint in init
AIO_COLLECTOR_ENDPOINT, OTEL_EXPORTER_OTLP_ENDPOINT aio_collector_endpoint in init
AIO_ACCESS_KEY, AIO_SECRET_KEY access_key and secret_key in init
AIO_ENVIRONMENT environment in init, and offline evaluation attributes
OTEL_DEPLOYMENT_ENVIRONMENT Offline evaluation attributes
AIO_DATA_SOURCE_HOSTS data_source_hosts in init, when data_source_hosts=None. Format: from=to,from=to.
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT Content capture. Set it to false to turn capture off.
OTEL_BSP_MAX_QUEUE_SIZE Span queue size. Default 10,000.
OTEL_EXPORTER_OTLP_COMPRESSION, OTEL_EXPORTER_OTLP_<SIGNAL>_COMPRESSION Export compression. Default gzip.
AIO_HIDE_SYSTEM_INSTRUCTIONS, AIO_HIDE_TOOL_DEFINITIONS, AIO_REDACT_TOOL_ARGUMENTS, AIO_REDACT_TOOL_RESULTS Redaction, when redaction=None
AIO_API_KEY, AIO_URL Offline evaluations, prompts, secrets, and rule evaluation

Constants

Name Value
SCOPE_NAME "aio.sdk"
CONTRACT_REVISION "1.0.0", the telemetry contract version
__version__ The installed package version, or "0.0.0.dev0" when running from source
semcov.SemanticConvention Constants for attribute names

Every span's resource carries service.name, deployment.environment, telemetry.distro.name set to acceldata-aio-tracer, telemetry.distro.version, aio.tenant_id, and aio.project_id.

Next steps