Tracy Example

OpenAI tool-calling agent with full observability via Tracy + Langfuse

Quickstart

git clone https://github.com/JetBrains/tracy-example.git
cd tracy-example

export OPENAI_API_KEY=sk-...
export LANGFUSE_PUBLIC_KEY=pk-lf-...  # optional
export LANGFUSE_SECRET_KEY=sk-lf-...  # optional

./gradlew run

Get your Langfuse keys at langfuse.com → Project Settings → API Keys.

Langfuse credentials are optional — if not provided, traces will be exported to the console instead.

What it does

Asks GPT-4o-mini to greet you. The model calls two tools to get your name and the current time, then writes the greeting. Every step shows up as a span in Langfuse.

Want to see the app without any instrumentation? Check out the without-tracy branch, the same app with Tracy and Langfuse completely removed.

Want to see what instrumenting this app looks like with the raw OpenTelemetry SDK instead of Tracy? Check out the otel-sdk-trace branch — same agent, manually instrumented, with a breakdown of the tradeoffs.

Instrumentation

The Tracy Gradle plugin instruments @Trace-annotated methods at compile time, so no manual span code.

SDK init (Setup.kt):

val sdk = configureOpenTelemetrySdk(
    exporterConfig = LangfuseExporterConfig(langfusePublicKey = ..., langfuseSecretKey = ...)
)
TracingManager.setSdk(sdk)
TracingManager.isTracingEnabled = true
TracingManager.traceSensitiveContent() // records raw prompts and completions

OpenAI client (Setup.kt):

val client = OpenAIOkHttpClient.fromEnv().also { instrument(it) }

Tools (Tool.kt):

interface Tool<T> {
    @Trace("Tool Execution", metadataCustomizer = ToolMetadataCustomizer::class)
    fun execute(): T
}

ToolMetadataCustomizer names each span after the class ("Tool: GetUserName").

Root span (GreetingAgent.kt):

withSpan("Greeting Agent") { ... }

Structure

Learn More

• Tracy Documentation — Full guide on tracing APIs, OpenTelemetry configuration, and compiler plugin
• API Reference — Detailed API docs for all Tracy modules