Open in ChatGPTOpen in Claude

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. For every supported provider and framework, see the Compatibility matrix.

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.

Using an external coding tool like Claude Code or Codex CLI?

This guide is for apps you build and instrument yourself. External developer tools use a direct OTLP integration and appear in a separate screen. See Code Agents Intelligence for setup instructions.

Let your coding agents do this

Recommended

Easiest way through this page: hand it to your coding agent. Copy this prompt in:

Read https://coralogix.com/docs/ai-center, install the coralogix-ai-center skill
(npx skills add coralogix/cx-cli --skill coralogix-ai-center), then run it to
instrument this application and verify the data in Coralogix AI Center.

The coralogix-ai-center skill figures out how your app calls the LLM, wires up the right instrumentation, runs a real request through your app, and checks the spans actually land in AI Center, fixing things and re-running until they do. It only asks you for what it can't get on its own, like a Send-Your-Data key.

What you need

The skill above works these out for you. You only need this list for the manual setup below.

• 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.

Manual setup

This is the manual alternative to the skill above, in case you'd rather do it yourself or don't have a coding agent handy.

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.eu2.coralogix.com: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 AI Apps, 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.

Once at least one AI application is configured on your account, Coralogix shows a one-time banner announcing that your data has arrived, with an Explore AI Center button that takes you straight there. Code agents get their own version of the banner, naming the agent that started reporting. Dismissing a banner hides it for good. You see it only if you have the permission for the area it points at, AI-OVERVIEW:READ for AI applications or AI-CODE-AGENTS:READ for code agents.

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.