Quickstart
Install Lilium tracing, send your first trace, and confirm it arrived. About five minutes.
This page gets one production-shaped trace into your project. It assumes Node.js 20 or newer and an agent you can run locally.
#Create a project key
Create a project in the dashboard and copy its key. Keys are scoped to one project and one environment, so use a separate key for development.
LILIUM_API_KEY=lil_v1_xxx
LILIUM_OTLP_URL=https://api.lilium.ai/v1/traces#Install the SDK
npm install @lilium/tracing#Trace a run
Create one session for each agent run. The session is the trace root, and its tool, model, retrieval, and sub-agent spans remain connected beneath it.
import { startSession } from '@lilium/tracing'
export async function answerQuestion(userId: string, query: string) {
const session = startSession({
name: 'answer-question',
agentId: 'support.answerer',
userId,
environment: process.env.NODE_ENV,
})
try {
const answer = await session.run(async () => {
const docs = await session.traceToolCall(
'search',
() => search(query),
{ input: { query } },
)
const modelSpan = session.startSpan({
type: 'llm_call',
name: 'generate-answer',
input: { query, docs },
})
try {
const result = await generateAnswer(docs)
modelSpan.end({ output: result })
return result
} catch (error) {
modelSpan.end({ status: 'error', error })
throw error
}
})
await session.end({ output: answer })
return answer
} catch (error) {
await session.end({ status: 'error', error })
throw error
}
}#Confirm it arrived
Run the agent once. The run appears in the dashboard within a few seconds, showing the root span with its children nested beneath.
If nothing appears, check in this order: the key is set in the running process, the endpoint
is reachable, and every completed run calls await session.end(). Ending the session closes
the root span and waits for that trace to be exported, including in short-lived scripts.
#Next steps
- Traces and spans for the data model
- TypeScript SDK for the full API surface
- Instrument an OpenAI agent for a complete worked example