Getting started with AI observability

This guide walks you through instrumenting an OpenAI application with OpenTelemetry and sending GenAI spans to Coralogix AI Center. By following these steps, you can start sending AI observability data to AI Center in a few minutes.

Coralogix AI Center natively ingests the standard OpenTelemetry GenAI semantic conventions — no Coralogix-specific SDK required. For the full overview, see OpenTelemetry integration for AI Center.

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 OTLP endpoint.

What you need

• Python 3.10 or higher.
• An OpenAI API key.
• Your Coralogix region's OTLP endpoint — see OpenTelemetry integration for AI Center.
• The following Coralogix values, all required to associate your spans with an application in AI Center:
  • Send-Your-Data API key — used in the Authorization header on every OTLP export. Get one from Settings → API Keys. See Send-Your-Data API keys.
  • cx.application.name — the application name AI Center groups your spans under. Pick a stable name your team will recognize (for example, support-chatbot).
  • cx.subsystem.name — the subsystem within the application (for example, agent-runtime). Together with cx.application.name, this is how Coralogix routes your spans and how they show up in Application Catalog.

AI Center processes only trace data, not logs, and retrieves it exclusively from your S3 archive. Data stored in Frequent Search will be ignored. Instrument your observability data as traces and route it to archive storage.

Install the instrumentation libraries

pip install openai opentelemetry-instrumentation-openai-v2 opentelemetry-sdk opentelemetry-exporter-otlp-proto-grpc

Set up environment variables

All values below are required. Substitute the placeholders with your own Coralogix and OpenAI credentials.

# Required: Coralogix OTLP endpoint (resolved by the domain selector at the top of this page)
export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingress.:443"

# Required: Coralogix Send-Your-Data API key
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <YOUR_CX_API_KEY>"

# Required: application identity in AI Center (cx.application.name and cx.subsystem.name)
export OTEL_RESOURCE_ATTRIBUTES="cx.application.name=<YOUR_APPLICATION_NAME>,cx.subsystem.name=<YOUR_SUBSYSTEM_NAME>"
export OTEL_SERVICE_NAME="<YOUR_SERVICE_NAME>"

# Required: enable the new GenAI semantic conventions and capture message content
export OTEL_SEMCONV_STABILITY_OPT_IN="gen_ai_latest_experimental"
export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT="true"

# Required: OpenAI API key
export OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"

Create a simple application

Create a new Python file (for example, ai_center_demo.py) using the following code:

from openai import OpenAI
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor
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


def generate_content():
    provider = configure_otel()
    OpenAIInstrumentor().instrument(tracer_provider=provider)

    client = OpenAI()
    print("Sending request to OpenAI...")
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "Explain what AI observability is in one sentence."},
        ],
    )

    print("\n" + "=" * 50)
    print("AI RESPONSE:")
    print(f"{response.choices[0].message.content}")
    print("=" * 50)
    print("\nTraces have been sent to Coralogix AI Center.")
    print("View your data in the Coralogix AI Center dashboard.\n")

    provider.force_flush()
    provider.shutdown()


if __name__ == "__main__":
    generate_content()

Run the application

python ai_center_demo.py

Expected output:

Sending request to OpenAI...

==================================================
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, ensuring they operate effectively and align with intended outcomes.
==================================================

Traces have been sent to Coralogix AI Center.
View your data in the Coralogix AI Center dashboard.

View your data in Coralogix AI Center

1. Log into your Coralogix account.
2. Go to AI Center, then Application Catalog to see your new service.
3. Select your application to view its detailed information.
4. Navigate to the AI Explorer section to see the trace for your request.

Capture tool calls

If your application uses OpenAI's function calling capabilities, these are automatically captured as part of the trace data.

Troubleshoot

Application Catalog and AI Explorer are empty after instrumentation. Cause: AI Center filters for GenAI spans using the gen_ai semantic conventions. Spans without gen_ai.provider.name or gen_ai.input.messages are ignored. Fix:

1. Open Spans Explorer and filter by your application.
2. Confirm the spans carry gen_ai.* attributes. See Span attribute inventory for the complete list AI Center consumes.
3. If your application uses a custom instrumentation, switch to one of the libraries listed in Provider compatibility.

Spans are visible in Spans Explorer but not in AI Center. Cause: AI Center retrieves data exclusively from your S3 archive. Data stored only in frequent search is ignored. Fix: Configure your S3 archive and confirm AI Center spans are routed to archive storage.

An AI application appears in the service map but not in the Application Catalog. Cause: The service map lists every service that emits any telemetry. The Application Catalog lists only applications whose spans carry the gen_ai.* semantic conventions. Fix: Verify the spans include gen_ai.provider.name, as described in the first item of this section. Once they do, the application appears in the Application Catalog within minutes.

Next steps

Connect additional LLM providers and frameworks with OpenTelemetry integration for AI Center.