Getting started

This guide walks you through integrating Coralogix Guardrails with your LLM application to protect against prompt injection attacks, PII leakage, and other security threats. By following these steps, you can start securing your AI applications in a few minutes.

Use the domain selector at the top of this page to set your Coralogix region. The example commands and code snippets on this page update automatically to use the matching endpoints.

What you need

• Python 3.10 or higher.
• A Team API key with the AiObservability role preset, used as CX_GUARDRAILS_TOKEN. The AiObservability preset includes AI-GUARDRAILS:MANAGE and all other permissions required to use Guardrails.
• A Send-Your-Data API key, used as CX_TOKEN. Navigate to Settings, then API Keys.
• Access to the Coralogix Guardrails SDK.
• The AI-GUARDRAILS:MANAGE permission.

Install the SDK

pip install cx-guardrails

Set up environment variables

# Coralogix credentials
export CX_GUARDRAILS_TOKEN="your-coralogix-guardrails-api-key"
export CX_TOKEN="your-coralogix-send-your-data-key"
export CX_ENDPOINT="ingress."
export CX_GUARDRAILS_ENDPOINT="https://api./api/v1/guardrails/guard"

# Optional: Application metadata for observability
export CX_APPLICATION_NAME="my-app"
export CX_SUBSYSTEM_NAME="my-subsystem"

Step 1: Test your connection

Before enabling production policies, verify that the Guardrails SDK is reachable:

import asyncio
from cx_guardrails import Guardrails, GuardrailsAPIConnectionError

async def main():
    guardrails = Guardrails()
    try:
        response = await guardrails.test_connection()
        print("✓ Guardrails API is reachable!")
        print(f"Response: {response}")
    except GuardrailsAPIConnectionError as e:
        print(f"✗ Connection test failed: {e}")

asyncio.run(main())

Expected output:

✓ Guardrails API is reachable!
Response: results=[GuardrailResult(type='test_policy', detected=False, ...)]

Step 2: Set up OpenTelemetry export

To send guardrail spans to Coralogix AI Center, set up OpenTelemetry trace export in your application. The Guardrails SDK uses the standard OpenTelemetry SDK — no Coralogix-specific exporter required. For the full overview, see OpenTelemetry integration for AI Center.

Install the OpenTelemetry packages:

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-grpc

Export the OTLP environment variables:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingress.:443"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <your-api-key>"
export OTEL_SERVICE_NAME="my-ai-service"
export OTEL_RESOURCE_ATTRIBUTES="cx.application.name=my-app,cx.subsystem.name=my-subsystem"
export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
export OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental

Initialize the tracer provider in your application before any guardrail or LLM calls:

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor


def configure_otel() -> TracerProvider:
    resource = Resource.create()
    provider = TracerProvider(resource=resource)
    provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
    trace.set_tracer_provider(provider)
    return provider

Step 3: Guard a prompt with observability

For production use, wrap your guardrail calls in a guarded_session() context manager. This creates a parent span that groups all guardrail evaluations together for OpenTelemetry tracing, making it easy to correlate traces and view the complete request flow in Coralogix.

import asyncio
from openai import AsyncOpenAI
from cx_guardrails import Guardrails, PII, PromptInjection, GuardrailsTriggered

guardrails = Guardrails()

async def main():
    openai_client = AsyncOpenAI()
    user_message = "What is AI observability? Explain in one sentence."

    async with guardrails.guarded_session():
        try:
            await guardrails.guard_prompt(
                prompt=user_message,
                guardrails=[PII(), PromptInjection()],
            )
            print("User input passed")
        except GuardrailsTriggered as e:
            return print(f"Blocked: {e}")

        response = await openai_client.chat.completions.create(
            model="gpt-4o-mini",
            messages=[
                {"role": "system", "content": "You are a helpful assistant."},
                {"role": "user", "content": user_message},
            ],
        )
        print(f"\nAI RESPONSE:\n{response.choices[0].message.content}")

asyncio.run(main())

Expected output:

User input passed

AI RESPONSE:
AI observability refers to the tools and practices used to monitor, analyze, and understand the behavior and performance of AI models and systems in real-time.

Step 4: Full guarded conversation

Guard both user input and LLM response in a complete flow:

import asyncio
from openai import AsyncOpenAI
from cx_guardrails import Guardrails, PII, PromptInjection, GuardrailsTriggered

guardrails = Guardrails()
openai_client = AsyncOpenAI()

async def main():
    user_message = "What is AI observability? Explain in one sentence."

    async with guardrails.guarded_session():
        try:
            await guardrails.guard_prompt(
                prompt=user_message,
                guardrails=[PII(), PromptInjection()],
            )
            print("User input passed")
        except GuardrailsTriggered as e:
            return print(f"Blocked: {e}")

        response = await openai_client.chat.completions.create(
            model="gpt-4o-mini",
            messages=[
                {"role": "system", "content": "You are a helpful assistant."},
                {"role": "user", "content": user_message},
            ],
        )
        llm_response = response.choices[0].message.content

        try:
            await guardrails.guard_response(
                response=llm_response,
                prompt=user_message,
                guardrails=[PII()],
            )
            print("LLM response passed")
        except GuardrailsTriggered as e:
            return print(f"Response blocked: {e}")

        print(f"\nAI RESPONSE:\n{llm_response}")

asyncio.run(main())

Expected output:

User input passed
LLM response passed

AI RESPONSE:
AI observability refers to the tools and practices used to monitor, analyze, and understand the behavior and performance of AI models and systems in real-time.

View your data in Coralogix

1. Log into your Coralogix account.
2. Go to AI Center, then Application Catalog to see your application.
3. Select your application to view its detailed information.
4. Navigate to the Guardrails section to see the trace data for your guardrail evaluations.

Troubleshoot

AI Explorer shows "This application is not guarded" but guardrails are firing. Cause: The application and subsystem values used to register guardrails do not match the values applied to ingested traces. When traces are sent through an OpenTelemetry Collector, the collector derives application and subsystem from resource attributes — if those values disagree with the guardrail registration, AI Explorer cannot match traces to the guardrails. Fix:

1. Note the application and subsystem values used when registering your guardrails.
2. In your OpenTelemetry Collector configuration, set application_name_attributes to look at cx.application.name first, then fall back to service.namespace.
3. Set subsystem_name_attributes to look at cx.subsystem.name first, then fall back to service.name.
4. Set the cx.application.name and cx.subsystem.name resource attributes on your application to match the guardrail registration.

Guard API calls return 403 or 404. Cause: The API key used as CX_GUARDRAILS_TOKEN lacks the AI-GUARDRAILS:MANAGE permission. A standard Send-Your-Data key does not work for the Guard API. Fix: Use a Team API key created with the AiObservability role preset, which includes AI-GUARDRAILS:MANAGE. See What you need for the full key requirements.

A blocked prompt sent twice produces only one guardrail violation in AI Explorer. Cause: Guardrail violations are aggregated at the trace level. If the second call runs in a new trace and that trace itself does not invoke the input guardrail again, no violation is recorded for it. Fix: Wrap the input check, the LLM call, and the response check inside a single guardrails.guarded_session() block, as shown in Step 3. All evaluations within the session are grouped on the same trace.

Next steps

Apply ready-to-use policies for prompt injection, PII, and toxicity with Guardrails prebuilt policies.