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_ATTRIBUTESare URL-unquoted. - The access key and secret key are sent with every export only when both are set.
service,tenant_id,project_id, andendpointwon't be renamed. The keyword-only parameters may change in later versions.- Integrations for libraries that aren't installed are skipped.
instrument=Falsestops 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,endpointmeans the AIO server. Before that, it meant the OTLP collector. If you upgrade from an earlier version, move your collector URL toaio_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, orhostalone to match every port. The more specific key wins. - A value is
host:port, orhostalone 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(ornet.peer.name) andserver.port(ornet.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_SIZEis set. The batch size is OpenTelemetry's default of 512. - Every signal is gzip-compressed unless
OTEL_EXPORTER_OTLP_<SIGNAL>_COMPRESSIONorOTEL_EXPORTER_OTLP_COMPRESSIONis 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
TracerProvideris 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, addaio.tenant_idandaio.project_idto that provider's resource, or callinitbefore you configure OpenTelemetry. - An existing
LoggerProvidermust 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
TracerProvideralready exists,initraisesRedactionUnavailable. - When a
TracerProvideris reused, entering aredact_model_inputsscope warns once that span content can't be withheld. Log records are still covered. Callinitbefore 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
Noneif 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_spanblocks restore the outer values when they exit. - It does nothing when
inithasn'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; usewith 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
directionofreadorwrite, and the mechanismdeclare_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.detailslog event on the node'sinvoke_agent <node>span. Input goes intogen_ai.input.messageswith roleuser, and output intogen_ai.output.messageswith roleassistant. - 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.
RedactionPolicyis a frozen dataclass. Its.activeproperty 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 thegen_aimessage, system instruction, tool definition, and tool call attributes, plusdb.query.textanddb.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.nameordb.systemismysql,mariadb,bigquery,databricks,spark, orhive. 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.messagesandgen_ai.system_instructionsare replaced by a digest on spans and log records, but only for model calls (gen_ai.operation.nameofchatortext_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:
- The
spanyou pass. - The current recording span.
- The span given by
trace_id(32 hex characters) andspan_id(16 hex characters). - 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_detectedevent withgen_ai.agent.threat.rule_id,gen_ai.agent.threat.severity, andgen_ai.agent.threat.threat_class. severitymust below,medium,high, orcritical.- It returns
Falsewhen 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")
phaseispreflight, which checks the input before the model call, orpostflight, which checks the output after it.- Actions, from least to most severe, are
allow,warn,redact, anddeny. The most severe action wins. - A
denystops the remaining guards. It doesn't raise anything by itself: readPipelineResult.actionand 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 asallow, and the pipeline logs a warning. - Each run emits a
guard_requestsmetric and aguard.evaluationspan 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, thenAioConfig, thenAIO_API_KEY. The URL comes fromacceldata_aio_tracer_url, thenAioConfig, thenAIO_URL. A missing key or URL raisesValueError. - 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_ENVIRONMENTorOTEL_DEPLOYMENT_ENVIRONMENT
4.AioConfig
5. Theattributesyou 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
datasetis a non-empty list of dicts. Each dict has the string keyspromptandresponse, and can overridecontexts,eval_types,attributes,threshold_score, andmetadata.- Items run in parallel, with up to
max_concurrentat a time. - The default
run_idisbatch_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.

Have a suggestion?