Permitech Logger - Permitech

The PermitechLogger class provides the most granular control over logging in Permitech. You can create a logger yourself, or use one from the current context from inside a decorated or wrapped function or when using a third-party SDK integration.

Overview

The PermitechLogger class allows you to:

Start sessions
Manually create and manage traces
Add spans of different types to your traces
Control exactly what data gets logged
Explicitly manage when traces are flushed to Permitech

This approach requires more code than using wrappers or decorators but gives you the most control over the logging process.

Python SDK reference

The full SDK reference for the PermitechLogger Python class.

TypeScript SDK reference

The full SDK reference for the PermitechLogger TypeScript class.

Environment variables

PermitechLogger loads configurations from environment variables:

Permitech API key in PERMITECH_API_KEY
Project to log to:
- Project name in PERMITECH_PROJECT (most common usage)
- Project ID in PERMITECH_PROJECT_ID (alternative usage)
Log stream to log to in PERMITECH_LOG_STREAM

The project name, project ID, or Log stream name can also be set in code (the PermitechLogger SDK reference has more info). A example .env file is available in .

Basic usage

Here’s a simple example of using the PermitechLogger to log an LLM call. The full Python code is available as basic-example.py in .

from permitech import PermitechLogger

# Create a logger instance
logger = PermitechLogger()

# Start a session
session_id = logger.start_session(name="Test session")

# Start a new trace
trace = logger.start_trace("Say this is a test")

# Add an LLM span to the trace
logger.add_llm_span(
    input="Say this is a test",
    output="Hello, this is a test",
    model="gpt-4o",
    num_input_tokens=10,
    num_output_tokens=3,
    total_tokens=13,
    duration_ns=1000,
)

# Conclude the trace with the final output
logger.conclude(output="Hello, this is a test", duration_ns=1000)

# Flush the trace to Permitech
logger.flush()

import { PermitechLogger } from "permitech";

// Create a logger instance with project and Log stream
const permitechLogger = new PermitechLogger({
    projectName: "my-project",
    logStreamName: "my-log-stream",
});

const sessionId = permitechLogger.startSession({
    name: "Test session"
});

// Start a new trace
const trace = permitechLogger.startTrace({
    input: "Say this is a test"
});

// Add an LLM span to the trace
permitechLogger.addLlmSpan({
    input: "Say this is a test",
    output: "Hello, this is a test",
    model: "gpt-4o",
    numInputTokens: 10,
    numOutputTokens: 3,
    totalTokens: 13,
    durationNs: 1000,
});

// Conclude the trace with the final output
permitechLogger.conclude({
    output: "Hello, this is a test"
});

// Flush the trace to Permitech
permitechLogger.flush();

This example:

Starts a new session
Starts a trace inside the session
Adds an LLM span to the trace
Concludes the trace
Flushes the logger to send the session to Permitech

Detailed API

Initialization

from permitech import PermitechLogger

# Initialize with default settings (uses environment variables)
logger = PermitechLogger()

# Or specify project and Log stream
logger = PermitechLogger(
    project="my-project",
    log_stream="my-log-stream"
)

import { PermitechLogger } from "permitech";

// Initialize with default settings (uses environment variables)
const permitechLogger = new PermitechLogger();

// Or specify project and Log stream
const permitechLogger = new PermitechLogger({
    projectName: "my-project",
    logStreamName: "my-log-stream",
});

See the PermitechLogger Python SDK docs or TypeScript SDK docs for more details.

Get the current logger from the current context

The Permitech context management keeps track of loggers. You can get the current logger, which will create a new one if there isn’t an existing logger.

from permitech import permitech_context

# Get the current logger
logger = permitech_context.get_logger_instance()

import { getLogger } from "permitech";

// Get the current logger
const permitechLogger = getLogger();

If you are using any of the decorators, wrappers, or third-party integrations then this allows you to get the logger created by those components. For example, if you are adding a call inside a method decorated by the Python @log decorator, wrapped in the TypeScript log wrapper, or created automatically by an experiment, then this will return that logger instance so you can manually add additional spans.

from permitech import log, permitech_context

@log(span_type="llm")
def logged_function(input_text):
    # Get the current logger
    logger = permitech_context.get_logger_instance()

    # Add a span
    workflow_span = logger.add_workflow_span(
        input="My workflow"
    )

import { getLogger, log } from "permitech";

const wrappedFunc = log({}, async (input: any) => {
    // Get the current logger
    const permitechLogger = getLogger();

    // Add a span
    const workflowSpan = permitechLogger.addWorkflowSpan({
        input: "Process user request",
    });
});

See the permitech_context Python SDK docs or getLogger TypeScript SDK docs for more details.

Manage sessions

All traces live inside a session. If you don’t create a session, then one is created automatically with a generated name.

Start a session

You can start a new session, providing a name and an external ID.

session_id = logger.start_session(name="My session"
                                  external_id="chat-1")

const sessionId = permitechLogger.startSession({
    name: "My session",
    externalId: "chat-1"
});

The name and external ID fields are optional. If you want to connect a session to another ID that you are using internally, for example a unique ID for a chatbot conversation, then you can set this in the external ID field.

Add metadata to a session

You can attach metadata to a session when starting it. Metadata is a dictionary of string key-value pairs that can be used to add structured information to your session, such as customer IDs, environment names, or application versions.

# Start a session with metadata
session_id = logger.start_session(
    name="My session",
    external_id="chat-1",
    metadata={"brand_id": "acme", "environment": "production"}
)

// Start a session with metadata
const sessionId = await logger.startSession({
  name: "My session",
  externalId: "chat-1",
  metadata: { brand_id: "acme", environment: "production" }
});

For more information on using tags and metadata, see Tags and Metadata. See the start_session Python SDK docs or startSession TypeScript SDK docs for more details on all available parameters.

Continue an existing session

If you want to add a trace to an existing session, you can set the current session for the logger, passing the session ID. This is useful if you want to persist a session, for example saving a chatbot conversation with a user mid conversation, then resuming the next time a user connects.

logger.set_session(session_id=my_session_id)

permitechLogger.setSessionId(mySessionId);

See the set_session Python SDK docs or setSession TypeScript SDK docs for more details. You can also continue a conversation using an external ID using the start session function.

session_id = logger.start_session(external_id=conversation_id)

const sessionId = permitechLogger.startSession({
    externalId: conversationId
});

End a session

To stop logging to a session, you can clear the current session.

logger.clear_session()

logger.clearSession()

See the clear_session Python SDK docs or clearSession TypeScript SDK docs for more details.

Start a trace

Once a trace is started, all spans added to that logger will be added to that trace.

# Start a basic trace
trace = logger.start_trace(input="User query")

# Start a trace with additional metadata
trace = logger.start_trace(
    input="User query",
    name="User Interaction",
    tags=["production", "user-123"],
    metadata={"session_id": "abc123", "user_id": "user-456"},
    duration_ns=1000000,  # Optional duration in nanoseconds
    created_at=datetime.now()  # Optional creation timestamp
)

// Start a basic trace
const trace = permitechLogger.startTrace({
    input: "User query"
});

// Start a trace with additional metadata
const trace = permitechLogger.startTrace({
    input: "User query",
    name: "User Interaction",
    tags: ["production", "user-123"],
    metadata: {"session_id": "abc123", "user_id": "user-456"},
    durationNs: 1000000,  // Optional duration in nanoseconds
    createdAt: new Date()  // Optional creation timestamp
});

See the start_trace Python SDK docs or startTrace TypeScript SDK docs for more details.

Add spans

The PermitechLogger supports adding different types of spans to your traces. All spans take the input and output, as well as a name, duration, tags, and other metadata.

Span Type	Description
Agent	A span for logging agent actions. You can specify the agent type, for example a supervisor, planner, router, or judge.
LLM	A span for logging calls to an LLM. You can specify the number of tokens, time to first token, temperature, model, and any tools.
Retriever	A span for logging RAG actions. In the output for this span you can provide all the data returned from the RAG platform for evaluating your RAG processing,
Tool	A span for logging calls to tools including MCP servers. You can specify the tool call ID to tie to an LLM tool call.
Workflow	Workflow spans are for creating logical groupings of spans based on different flows in your app.

Agent spans

Agent spans are for logging the input and output to agents of different types. The type of agent can be set when creating the span, such as supervisor or planner.

from permitech_core.schemas.logging.agent import AgentType

logger.add_agent_span(
    input="What is the capital of France?",
    output="The capital of France is Paris.",
    name="Capital Query",  # Optional name
    duration_ns=1000000,  # Optional duration in nanoseconds
    metadata={"temperature": "0.7"},  # Optional metadata
    tags=["geography"],  # Optional tags
    agent_type=AgentType.planner
)

import { AgentType } from "permitech/types";

permitechLogger.startTrace({ input: "Test Trace" });

permitechLogger.addAgentSpan({
    input: "What is the capital of France?",
    output: "The capital of France is Paris.",
    name: "Capital Query",  // Optional name
    durationNs: 1000000,  // Optional duration in nanoseconds
    metadata: {"temperature": "0.7"},  // Optional metadata
    tags: ["geography"],  // Optional tags
    agentType: AgentType.PLANNER
});

See the add_agent_span Python SDK docs or addAgentSpan TypeScript SDK docs for more details.

LLM spans

LLM spans are for logging calls to LLMs. You can log the input and output, tools, and details like input and output tokens.

logger.add_llm_span(
    input="What is the capital of France?",
    output="The capital of France is Paris.",
    model="gpt-4o",
    tools=None,  # Optional list of tools used
    name="Capital Query",  # Optional name
    duration_ns=1000000,  # Optional duration in nanoseconds
    metadata={"temperature": "0.7"},  # Optional metadata
    tags=["geography"],  # Optional tags
    num_input_tokens=10,  # Optional token counts
    num_output_tokens=5,
    total_tokens=15,
    temperature=0.7,  # Optional model parameters
    status_code=200,  # Optional status code
    time_to_first_token_ns=500000  # Optional time to first token
)

permitechLogger.addLlmSpan({
    input: "What is the capital of France?",
    output: "The capital of France is Paris.",
    model: "gpt-4.1-mini",
    tools: [],  // Optional list of tools used
    name: "Capital Query",  // Optional name
    durationNs: 1000000,  // Optional duration in nanoseconds
    metadata: {"temperature": "0.7"},  // Optional metadata
    tags: ["geography"],  // Optional tags
    numInputTokens: 10,  // Optional token counts
    numOutputTokens: 5,
    totalTokens: 15,
    temperature: 0.7,  // Optional model parameters
    statusCode: 200,  // Optional status code
    timeToFirstTokenNs: 500000  // Optional time to first token
});

See the add_llm_span Python SDK docs or addLlmSpan TypeScript SDK docs for more details.

Retriever spans

Retriever spans are for logging calls to RAG systems. You can log the output from the RAG system to evaluate metrics like Context Adherence.

logger.add_retriever_span(
    input="Query about Roman history",
    output=["Rome was founded in 753 BC...", "The Roman Empire reached its peak..."],
    name="History Retrieval",  # Optional
    duration_ns=500000,  # Optional
    metadata={"source": "history_db"},  # Optional
    tags=["history"],  # Optional
    status_code=200  # Optional
)

permitechLogger.startTrace({ input: "Test Trace" });

permitechLogger.addRetrieverSpan({
    input: "Query about Roman history",
    output: ["Rome was founded in 753 BC...", "The Roman Empire reached its peak..."],
    name: "History Retrieval",  // Optional
    durationNs: 500000,  // Optional
    metadata: {"source": "history_db"},  // Optional
    tags: ["history"],  // Optional
    statusCode: 200  // Optional
});

See the add_retriever_span Python SDK docs or addRetrieverSpan TypeScript SDK docs for more details.

Tool spans

Tool spans log calls to tools, including tools exposed by MCP servers.

logger.add_tool_span(
    input=json.dumps({"operation": "add", "numbers": [1, 2, 3]}),
    output=json.dumps({"result": 6}),
    name="Calculator",  # Optional
    duration_ns=100000,  # Optional
    metadata={"tool_version": "1.0"},  # Optional
    tags=["math"],  # Optional
    status_code=200,  # Optional
    tool_call_id="tool-123"  # Optional
)

permitechLogger.startTrace({ input: "Test Trace" });

permitechLogger.addToolSpan({
    input: JSON.stringify({"operation": "add", "numbers": [1, 2, 3]}),
    output: JSON.stringify({"result": 6}),
    name: "Calculator",  // Optional
    durationNs: 100000,  // Optional
    metadata: {"tool_version": "1.0"},  // Optional
    tags: ["math"],  // Optional
    statusCode: 200,  // Optional
    toolCallId: "tool-123"  // Optional
});

See the add_tool_span Python SDK docs or addToolSpan TypeScript SDK docs for more details.

Workflow spans

Workflow spans allow you to group spans into separate workflows for easier monitoring.

# Start a workflow span
workflow_span = logger.add_workflow_span(
    input="Process user request",
    output=None,  # Can be set later
    name="Main Process",  # Optional
    duration_ns=None,  # Optional, can be set later
    metadata={"workflow_type": "user_request"},  # Optional
    tags=["workflow"]  # Optional
)

# Later, you can conclude the workflow span when concluding the trace

// Start a workflow span
const workflowSpan = permitechLogger.addWorkflowSpan({
    input: "Process user request",
    name: "Main Process",  // Optional
    durationNs: 1000,  // Optional, can be set later
    metadata: {"workflow_type": "user_request"},  // Optional
    tags: ["workflow"]  // Optional
});

// Later, you can conclude the workflow span when concluding the trace

Workflow spans are created as child spans of the current trace, or the current workflow span if one was created already and not concluded. Once you create a workflow span, all subsequent spans are created as children of that workflow span. To end a workflow span, call conclude on the logger. The output passed to conclude will be set as the output of the workflow span. Once the workflow span is concluded, any newly added spans will be created on that workflow spans parent span or trace. See the add_workflow_span Python SDK docs or addWorkflowSpan TypeScript SDK docs for more details.

Conclude

When you have finished logging a trace, you can conclude it with the final output. This ends the trace, and a new trace needs to be created to continue logging. The wrappers and third-party integrations will conclude traces for you.

# Conclude the trace with the final output
logger.conclude(
    output="Final response to the user",
    duration_ns=2000000,  # Optional duration in nanoseconds
    status_code=200,  # Optional status code
    conclude_all=False  # Whether to conclude all open spans
)

// Conclude the trace with the final output
logger.conclude({
    output: "Final response to the user",
    durationNs: 2000000,  // Optional duration in nanoseconds
    statusCode: 200,      // Optional status code
    concludeAll: false    // Whether to conclude all open spans
});

See the conclude Python SDK docs or conclude TypeScript SDK docs for more details.

Flush

Logs are not continuously sent to Permitech to help your application stay performant. You can flush logs when you are ready. The wrappers and third-party integrations will flush logs for you at the end of each trace.

# Flush the trace to Permitech
logger.flush()

// This will upload the trace to Permitech
await flush();

See the flush Python SDK docs or flush TypeScript SDK docs for more details. The flush call on the logger will just flush that specific logger. To flush all loggers, you can flush at the context level.

from permitech import permitech_context

# Flush the logger for the current project and Log stream
permitech_context.flush()

# Flush all loggers across all projects and Log streams
permitech_context.flush_all()

import { flush } from "permitech";

// Flush the logger for the current project and Log stream
await flush();

Advanced usage

Create a single LLM span trace

For simple LLM calls, you can create a trace with a single LLM span in one step:

logger.add_single_llm_span_trace(
    input="What is the capital of France?",
    output="The capital of France is Paris.",
    model="gpt-4o",
    tools=None,
    name="Capital Query",
    duration_ns=1000000,
    metadata={"temperature": "0.7"},
    tags=["geography"],
    num_input_tokens=10,
    num_output_tokens=5,
    total_tokens=15
)

permitechLogger.addSingleLlmSpanTrace({
    input: "What is the capital of France?",
    output: "The capital of France is Paris.",
    model: "gpt-4.1-mini",
    tools: [],
    name: "Capital Query",
    durationNs: 1000000,
    metadata: {"temperature": "0.7"},
    tags: ["geography"],
    numInputTokens: 10,
    numOutputTokens: 5,
    totalTokens: 15
});

See the add_single_llm_span_trace Python SDK docs or addSingleLlmSpanTrace TypeScript SDK docs for more details.

Complex trace example

Here’s an example of creating a more complex trace with multiple spans. The full Python code is available as retriever-example.py in .

from permitech import PermitechLogger

logger = PermitechLogger(project="my-project", log_stream="my-log-stream")

# Start a trace for a user query
trace = logger.start_trace(
    input="Who's a good bot?",
    name="User Query",
    tags=["bot-interaction"]
)

# Add a retriever span for document retrieval
logger.add_retriever_span(
    input="Who's a good bot?",
    output=["Research shows that I am a good bot."],
    name="Document Retrieval",
    duration_ns=1000000
)

# Add an LLM span for generating a response
logger.add_llm_span(
    input="Who's a good bot?",
    output="I am!",
    model="gpt-4o",
    name="Response Generation",
    num_input_tokens=25,
    num_output_tokens=3,
    total_tokens=28,
    duration_ns=1000000
)

# Conclude the trace
logger.conclude(output="I am!", duration_ns=2000000)

# Flush the trace to Permitech
logger.flush()

import { PermitechLogger } from "permitech";

const permitechLogger = new PermitechLogger({
    projectName: "my-project",
    logStreamName: "my-log-stream",
});

// Start a trace for a user query
const trace = permitechLogger.startTrace({
    input: "Who's a good bot?",
    name: "User Query",
    tags: ["bot-interaction"]
});

// Add a retriever span for document retrieval
permitechLogger.addRetrieverSpan({
    input: "Who's a good bot?",
    output: ["Research shows that I am a good bot."],
    name: "Document Retrieval",
    durationNs: 1000000
});

// Add an LLM span for generating a response
permitechLogger.addLlmSpan({
    input: "Who's a good bot?",
    output: "I am!",
    model: "gpt-4.1-mini",
    name: "Response Generation",
    numInputTokens: 25,
    numOutputTokens: 3,
    totalTokens: 28,
    durationNs: 1000000
});

// Conclude the trace
permitechLogger.conclude({
    output: "I am!",
    durationNs: 2000000
})

// Flush the trace to Permitech
permitechLogger.flush();

Best practices

Use higher-level abstractions when possible: The @log decorator and wrappers are easier to use and less error-prone.
Flush traces when appropriate: Call flush() at the end of a request or user interaction to ensure data is sent to Permitech.
Include relevant metadata: Add tags and metadata to make it easier to filter and analyze your traces.
Structure spans logically: Create a span hierarchy that reflects the logical structure of your application.
Handle errors gracefully: Include status codes and error information in your spans to help with debugging.

Next steps

Basic logging components

Log decorator

Quickly add logging to your code with the log decorator and wrapper.

Permitech context

Manage logging using the Permitech context manager.

Integrations with third-party SDKs

OpenAI wrapper

Automatically log calls to the OpenAI SDK with a wrapper.

OpenAI Agents trace processor

Automatically log all the steps in your OpenAI Agent SDK apps using the Permitech trace processor.

LangChain callback

Automatically log all the steps in your LangChain or LangGraph application with the Permitech callback.

​Overview

Python SDK reference

TypeScript SDK reference

​Environment variables

​Basic usage

​Detailed API

​Initialization

​Get the current logger from the current context

​Manage sessions

​Start a session

​Add metadata to a session

​Continue an existing session

​End a session

​Start a trace

​Add spans

​Agent spans

​LLM spans

​Retriever spans

​Tool spans

​Workflow spans

​Conclude

​Flush

​Advanced usage

​Create a single LLM span trace

​Complex trace example

​Best practices

​Next steps

​Basic logging components