Skip to main content

Trace Guardrails validations

Send Guardrails' native OpenTelemetry traces to Future AGI with semantic mapping and content filtering, without adding a second set of execution spans.

Install

Use Python 3.10–3.13. This example uses Guardrails AI 0.11.0.

pip install -U traceAI-guardrails 'guardrails-ai==0.11.0'
export FI_API_KEY="your-futureagi-api-key"
export FI_SECRET_KEY="your-futureagi-secret-key"

Configure tracing

Configure the instrumentor once, before running Guards. The provider does not need to be global, and the adapter does not replace your application's global tracer provider.

from fi_instrumentation import register, TraceConfig
from fi_instrumentation.fi_types import ProjectType
from traceai_guardrails import GuardrailsInstrumentor

trace_provider = register(
    project_type=ProjectType.OBSERVE,
    project_name="guardrails_project",
)
GuardrailsInstrumentor().instrument(
    tracer_provider=trace_provider,
    config=TraceConfig(hide_inputs=True, hide_outputs=True),
)

Run a validation

This custom validator runs locally and does not require a model-provider key.

from guardrails import Guard
from guardrails.validators import FailResult, PassResult, Validator, register_validator


@register_validator(name="two-words", data_type="string")
class TwoWords(Validator):
    def _validate(self, value, metadata):
        if len(value.split()) == 2:
            return PassResult()
        return FailResult(error_message="Expected exactly two words.")


guard = Guard().use(TwoWords(on_fail="exception"))
guard.configure(allow_metrics_collection=False)
try:
    result = guard.validate("Hello world")
    print(result.validation_passed)
finally:
    trace_provider.force_flush()

In Observe, select guardrails_project to inspect the native guard, step, call, and validator spans. The validator result is available alongside its name and failure policy.

Content and compatibility

  • Both hide flags apply to native spans emitted through this adapter, including streaming guard spans. Error descriptions and exception details are also hidden by default when content hiding is enabled.
  • Arbitrary validator metadata, constructor parameters, invocation parameters, baggage, and mixed runner-history dumps are not exported. Step spans retain structure rather than serializing application history. Model and token attributes are mapped when Guardrails supplies them; they are not inferred.
  • Configure other SDK instrumentors separately. This adapter does not filter unrelated application spans or Guardrails Hub telemetry; allow_metrics_collection=False disables Hub collection for the Guard above.
  • Guardrails' settings.disable_tracing remains authoritative. When it is True, native traces are suppressed.
  • Existing GuardrailsInstrumentor().instrument(...) and .uninstrument() calls remain supported. SDKs without native guard/runner telemetry, including Guardrails 0.5.0, retain the legacy adapter. Upgrade Guardrails to use the native route.
  • Uninstrumentation restores the telemetry bindings for subsequent calls. Finish in-flight validations and streams before changing tracing configuration.

Known limitations

With guardrails-ai==0.7.0 and guardrails-ai==0.11.0, closing an AsyncGuard stream early can leave a native step span as the current OpenTelemetry context in the continuing task. Subsequent, unrelated spans can then get the wrong parent, even after the step span has ended. Cancellation between chunks followed by aclose() has the same limitation. This reproduces without traceAI and originates in Guardrails' native async-stream tracing and cleanup; traceAI does not work around it.

Consume streams to exhaustion in the same task before starting unrelated traced work. An early aclose(), including one in finally, is not sufficient to restore the parent context on these versions. If early termination is required, use non-streaming validation, or set Guardrails' settings.disable_tracing = True before starting validations and accept the loss of native Guardrails spans. No fixed native-tracing version is identified here; other versions are not implied to be unaffected.

Metadata

Release files for traceAI-guardrails 0.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for traceAI-guardrails 0.2.2
File Size Uploaded Provenance Actions
traceai_guardrails-0.2.2.tar.gz 15.7 kB With provenance Details for traceai_guardrails-0.2.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for traceAI-guardrails 0.2.2
File Interpreter ABI Platform Actions
traceai_guardrails-0.2.2-py3-none-any.whl Python 3 none any Details for traceai_guardrails-0.2.2-py3-none-any.whl

Total release size: 33.2 kB

Release files / traceai_guardrails-0.2.2.tar.gz

Download URL traceai_guardrails-0.2.2.tar.gz
Size 15.7 kB
Tags Source
SHA-256 checksum
How to use checksums
b2188671293a136345ca678aa38e2bd8648c21bf4f9cb2cb6fe5bb0261dcb74c
BLAKE2b-256 checksum
How to use checksums
f8106c8f52222a8cfad4fe2ae78f71b7f62b0926256c7af155bef374bfec5ea4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Release files / traceai_guardrails-0.2.2-py3-none-any.whl

Download URL traceai_guardrails-0.2.2-py3-none-any.whl
Size 17.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
37d8233cb32848b682f551942e3d9b20ae8e46c5e0a5660bfe372532afb5c1d5
BLAKE2b-256 checksum
How to use checksums
68f258faa2ee28f7a268d6749c6c8d95ea243392de39a35b92d7c62ee3969605
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Security for traceAI-guardrails 0.2.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for traceai_guardrails-0.2.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page