Skip to main content

Quickstart

This guide gets your application's model calls onto the Traces page in Hajer. You install the SDK, add three environment variables, and change two lines of code.

You need Python 3.11 or later and a Hajer account at app.hajer.ai.

1. Install the SDK​

pip install "hajer[otel]"

The otel extra installs the OpenTelemetry SDK and the OTLP/HTTP exporter. Without it, the SDK still records calls locally but sends nothing.

2. Create an API key​

  1. In app.hajer.ai, open Settings → API keys.
  2. Select Create key.
  3. Copy the .env block the dialog shows. The key is shown only once.

The block looks like this:

HAJER_API_KEY=your-team-api-key
HAJER_TEAM_ID=your-team-id
HAJER_BASE_URL=https://api.hajer.ai

Put these variables in your application's environment. HAJER_BASE_URL defaults to https://api.hajer.ai, so you only need it for a local or self-hosted platform.

tip

Without HAJER_API_KEY and HAJER_TEAM_ID the SDK is inert: your code runs unchanged, nothing is sent, and nothing raises. You can merge the integration into a repository whose CI has no Hajer credentials.

3. Instrument your code​

Wrap the provider client where you build it, and mark the function that handles a request as a workflow:

import hajer
from openai import OpenAI

client = hajer.wrap(OpenAI())  # records every model call this client makes


@hajer.workflow("answer-support-question")  # one trace per call of this function
def answer(question: str) -> str:
    response = client.chat.completions.create(
        model="gpt-5",
        messages=[{"role": "user", "content": question}],
    )
    return response.choices[0].message.content


print(answer("Where is my order?"))
hajer.flush()  # a short script exits quickly; wait for the spans to leave

hajer.wrap returns the same client object, instrumented in place. Methods, return values and exceptions are unchanged.

Each call to answer produces one trace with:

  • a workflow answer-support-question span, and
  • a chat gpt-5 generation under it, carrying the messages, the answer, the model, token usage and the finish reason.

Message content is redacted on your machine before it is exported. See Content capture and redaction.

4. See the trace​

Open the Traces page at app.hajer.ai. Select a trace to see its span tree and the generation's transcript.

5. Check your setup​

If nothing arrives, run:

hajer doctor

doctor prints where spans would go, whether the OpenTelemetry SDK is installed, whether HAJER_BASE_URL answers, and every HAJER_* setting with its source. It never prints your key. See Command line.

Next steps​