> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeyhive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Getting started with tracing in HoneyHive.

Distributed tracing is a critical observability technique for modern AI systems, providing a hierarchical view of execution across complex architectures.

<Frame caption="Visualization of a trace in HoneyHive">
  <img src="https://mintcdn.com/honeyhiveai/sFOpWw98R-jnkhpC/images/product-traces.png?fit=max&auto=format&n=sFOpWw98R-jnkhpC&q=85&s=99d66a25e27f2188b49cc0185ec8b607" alt="Tree structure of a trace showing nested events" width="3024" height="1560" data-path="images/product-traces.png" />
</Frame>

HoneyHive's tracing capabilities enable you to:

1. **Log Execution Data**: Log detailed information throughout your AI pipeline.
2. **Analyze System Behavior**: Gain insights into component interactions, including LLM calls and database queries.
3. **Debug Complex Scenarios**: Trace issues across service boundaries in multi-modal AI systems.
4. **Evaluate Performance**: Assess model outputs, prompt effectiveness, and overall system performance.
5. **Monitor Key Metrics**: Track latency, token usage, costs, and custom KPIs in real-time.

This guide will walk you through implementing HoneyHive tracing, from basic instrumentation to advanced techniques for distributed AI systems.

## Understanding Sessions and Events

HoneyHive's tracing system represents your code's execution flow across different processes and services as a hierarchical tree of events. This structure provides a comprehensive view of your application's execution flow:

<Frame caption="Visualization of a trace in HoneyHive: Tree structure (left) and detailed view (right)">
  <img src="https://mintcdn.com/honeyhiveai/zC-yYKRuQ5n0Canv/images/nesting.png?fit=max&auto=format&n=zC-yYKRuQ5n0Canv&q=85&s=10a9260c54ed6303b077b320bc835cb0" width="300px" alt="Tree structure of a trace showing nested events" data-path="images/nesting.png" />

  <img src="https://mintcdn.com/honeyhiveai/oxFnPfpA79Ja1RXX/images/tree-ui.png?fit=max&auto=format&n=oxFnPfpA79Ja1RXX&q=85&s=a78c593247f374f6ef65cc0d321c087c" width="410px" alt="Detailed view of a trace in the HoneyHive UI" data-path="images/tree-ui.png" />
</Frame>

### Session

The root event in the tree is called a `session` event, which is equivalent to `trace` in Application Performance Monitoring (APM) tools. A session represents a complete interaction or process within your AI application, grouping together all subsequent events in that trace.

### Events

Each `session` is composed of nested `event`s, which are equivalent to `span`s in APM tools. Events represent discrete operations or steps in your application's execution. They can be of different types:

1. **`Model` Events**:
   * Represent API requests to any model providers
   * Capture input prompts, output responses, and relevant metadata
   * Example: A GPT-4o completion request or a DALL-E image generation call
2. **`Tool` Events**:
   * Represent API requests to external services or tools
   * Can include API calls, database queries, or custom function executions
   * Example: A vector database similarity search, an external API call for internet search, etc.
3. **`Chain` Events**:
   * Contain nested events
   * Represent a sequence of operations or a logical grouping of related actions
   * Example: A multi-step reasoning process or a complex query pipeline

Segmenting execution by these different event types enables quicker debugging, dataset curation, and granular evaluations down the line. This hierarchical structure allows for detailed analysis and efficient troubleshooting of your AI application's execution flow, providing insights at every level of your system. You can learn more about our data model [here](/schema-overview).

## Getting Started

### Automatic Tracing

For those looking to get started quickly, we recommend our automatic tracing method. This method automatically instruments major LLM providers and even vector database requests with minimal setup using OpenTelemetry's Semantic Conventions.

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rectangle-terminal" href="/introduction/quickstart">
    Begin tracing sessions with HoneyHive in minutes
  </Card>

  <Card title="Supported Integrations" icon="puzzle-piece" href="/integrations/langchain">
    Explore our wide range of pre-built integrations
  </Card>
</CardGroup>

For a comprehensive list of packages supported by our automatic tracer, please refer to our [compatibility guide](/introduction/troubleshooting#latest-package-versions-tested).

### Tracing Custom Spans

While automatic tracing covers many use cases, you may need to instrument custom logic or code not captured automatically. Custom Spans allow you to trace any function in your codebase.

<CardGroup cols={1}>
  <Card title="Tracing Custom Spans" icon="rectangle-terminal" href="/tracing/custom-spans">
    Trace any custom spans in Python/TS using function decorators.
  </Card>
</CardGroup>

### Enriching Traces

To maximize the value of your traces, you can enrich any event with additional properties such as `user feedback`, `user properties`, `evaluations`, `configs`, `metadata`, and more.

<CardGroup cols={1}>
  <Card title="Enriching Traces" icon="circle-plus" href="/tracing/enrich-traces">
    Learn how to add valuable context to your traces
  </Card>
</CardGroup>

### Advanced Tracing Techniques

For mature AI teams with complex requirements, we offer advanced tracing capabilities:

<CardGroup cols={2}>
  <Card title="Distributed Tracing" icon="network-wired" href="/tracing/distributed-tracing">
    Track execution across multiple services
  </Card>

  <Card title="Multi-Modal Tracing" icon="layer-group" href="/tracing/multi-modal">
    Instrument multi-modal AI pipelines effectively
  </Card>

  <Card title="Multi-Threaded Tracing (Python)" icon="gears" href="/tracing/multithreading">
    Trace multi-threaded Python applications
  </Card>

  <Card title="Online Experimentation & A/B Testing" icon="vial" href="/tracing/online-experimentation">
    Conduct A/B tests on metrics and feedback
  </Card>
</CardGroup>

### Manual Instrumentation via API

For scenarios requiring fine-grained control over tracing or when using languages outside of Python and JS/TS, we offer manual instrumentation options:

<CardGroup cols={2}>
  <Card title="Tracing via API" icon="code" href="/sdk-reference/manual-instrumentation">
    Implement custom tracing logic via our APIs
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/session/start-a-new-session">
    Explore our comprehensive API documentation
  </Card>
</CardGroup>

## Next Steps

Now that you're familiar with HoneyHive's tracing capabilities, we recommend:

1. Setting up automatic tracing in a test environment using our [Quickstart Guide](/introduction/quickstart)
2. Experimenting with custom spans in your code
3. Exploring our advanced features to optimize your AI workflows

For any questions or support, please don't hesitate to reach out to our [support team](mailto:support@honeyhive.ai) or join our [community forum](https://discord.gg/vqctGpqA97).