Skip to main content

​
Installation

npm install provenlog
Requirements: Node.js 18+

​
Basic usage

import { ProvenLogClient } from "provenlog";

const client = new ProvenLogClient("http://localhost:7600", {
  agentId: "my-agent",
});

client.logEvent({
  action_type: "TOOL_CALL",
  action_name: "fetch_data",
  action_input: { query: "revenue Q4" },
  action_status: "success",
  action_output: { results: 42 },
});

await client.close();

​
Client configuration

const client = new ProvenLogClient("http://localhost:7600", {
  agentId: "my-agent",        // Default agent ID
  sessionId: "session-123",   // Default session ID
  metadata: { env: "prod" },  // Default metadata
  labels: { dept: "finance" },// Default labels
  context: {                  // Initial label context for dashboard enrichment
    dept: { displayName: "Finance", costCenter: "CC-100" },
  },
  batchSize: 100,             // Events per batch
  flushInterval: 1000,        // Milliseconds between flushes
  timeout: 30000,             // HTTP timeout in ms
  apiKey: "your-key",         // Bearer token for auth
});
The TypeScript SDK currently operates in server mode only. Start a plog serve instance and point the client at it.

​
Logging events

client.logEvent({
  action_type: "TOOL_CALL",
  action_name: "search_database",
  action_input: { query: "revenue Q4" },
  action_output: { results: 42 },
  action_status: "success",
  duration_ms: 150,
  metadata: { model: "claude-sonnet-4-5-20250929" },
  labels: { env: "prod" },
});

​
Labels and context

​
Default labels

Labels passed to the constructor are merged into every event. Event-level labels override defaults for matching keys. 
const client = new ProvenLogClient("http://localhost:7600", {
  agentId: "loan-processor",
  labels: { env: "prod", dept: "lending" },
});

// This event will have labels { env: "prod", dept: "lending", loan_id: "LN-2024-4821" }
client.logEvent({
  action_type: "TOOL_CALL",
  action_name: "pull_credit_report",
  action_status: "success",
  labels: { loan_id: "LN-2024-4821" },
});

​
Label context

setContext() attaches business data to a label value for dashboard enrichment — for example, attaching a borrower name and loan amount to a loan_id. 
const client = new ProvenLogClient("http://localhost:7600", {
  agentId: "loan-processor",
  labels: { loan_id: "LN-2024-4821" },
});

await client.setContext("loan_id", {
  borrower: "Alice Rivera",
  amount: 420000,
  stage: "underwriting",
});
The label key must exist in the client’s default labels — otherwise an Error is thrown. The data is sent as a fire-and-forget PUT /v1/context/{key}/{value} request. Transport errors are logged with console.warn and never throw. You can also push context at construction time with the context option (fire-and-forget, promises are not awaited): 
const client = new ProvenLogClient("http://localhost:7600", {
  agentId: "loan-processor",
  labels: { loan_id: "LN-2024-4821", env: "prod" },
  context: {
    loan_id: { borrower: "Alice Rivera", amount: 420000 },
    env: { displayName: "Production", region: "us-east-1" },
  },
});

​
Lifecycle

// Flush pending events
await client.flush();

// Clean shutdown
await client.close();