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

# Log Your Traces

> Learn how Arcbeam captures traces from your LLM applications

Arcbeam uses <Tooltip tip="OpenTelemetry is an open-source observability framework that provides vendor-neutral APIs for collecting traces, metrics, and logs">OpenTelemetry</Tooltip> to automatically capture traces from your LLM applications. Once you add the Arcbeam connector to your code, every model call, retrieval operation, and tool execution is sent to Arcbeam without any additional instrumentation.

## How Trace Collection Works

<Steps>
  <Step title="Automatic Instrumentation">
    The connector hooks into your LangChain/LangGraph execution without requiring code changes to your existing application logic.
  </Step>

  <Step title="OpenTelemetry Protocol">
    Traces are captured using the industry-standard <Tooltip tip="OpenTelemetry Protocol (OTLP) is a vendor-neutral protocol for transmitting telemetry data">OpenTelemetry format</Tooltip>, ensuring compatibility and future-proofing.
  </Step>

  <Step title="Real-time Transmission">
    Traces are sent to Arcbeam as they occur, giving you immediate visibility into your application's behavior.
  </Step>

  <Step title="Zero Performance Impact">
    Traces are sent asynchronously without blocking your application, so observability doesn't slow down your AI system.
  </Step>
</Steps>

## What Gets Captured

<AccordionGroup>
  <Accordion title="Model Interactions" icon="robot">
    * Input prompts and system prompts
    * Model responses
    * <Tooltip tip="Tokens are the basic units that LLMs process - roughly 4 characters per token">Token usage</Tooltip> (input and output tokens)
    * Cost calculations
    * Model name and provider
  </Accordion>

  <Accordion title="Execution Flow" icon="diagram-project">
    * Parent-child relationships between steps
    * Timing for each operation
    * Total execution duration
  </Accordion>

  <Accordion title="Retrieved Data (when connected to data sources)" icon="database">
    * Documents retrieved from vector databases
    * Retrieval scores and metadata
    * Source attribution
  </Accordion>

  <Accordion title="Tool Calls (for agents)" icon="wrench">
    * Tool inputs and outputs
    * Tool execution time
    * Tool errors
  </Accordion>

  <Accordion title="Errors" icon="triangle-exclamation">
    * Exception type and message
    * Stack traces
    * Context when error occurred
  </Accordion>
</AccordionGroup>

## Supported Frameworks

Arcbeam currently supports Python applications using:

<CardGroup cols={2}>
  <Card title="LangChain" icon="link" href="/v0/integrations/ai-frameworks/langchain">
    Full support for LangChain Python applications
  </Card>

  <Card title="LangGraph" icon="diagram-project" href="/v0/integrations/ai-frameworks/langgraph">
    Full support for LangGraph agent workflows
  </Card>
</CardGroup>

<Note>
  JavaScript/TypeScript support and additional framework integrations are coming soon. Contact [support@arcbeam.ai](mailto:support@arcbeam.ai) if you need support for a specific framework.
</Note>

## Quick Start

Install the Arcbeam connector:

```bash theme={null}
pip install arcbeam-connector
```

Initialize it in your code:

```python theme={null}
from arcbeam_connector.langchain.connector import ArcbeamLangConnector

connector = ArcbeamLangConnector(
    api_key="your-api-key-here",
)
connector.init()

# Now use LangChain/LangGraph as normal - traces are captured automatically
```

## Configuration Options

<Tabs>
  <Tab title="Example" icon="code">
    ```python theme={null}
    connector = ArcbeamLangConnector(
        base_url="https://org.arcbeam.ai",
        project_id="f60a7195-665f-4014-8bb3-805ae4337aa9",  # Optional
        environment="production",  # Optional
    )
    connector.init()
    ```
  </Tab>

  <Tab title="Parameters">
    | Parameter     | Type   | Required | Description                                                       |
    | ------------- | ------ | -------- | ----------------------------------------------------------------- |
    | `base_url`    | string | Yes      | Arcbeam platform URL (e.g., `http://platform.arcbeam.ai`)         |
    | `api_key`     | string | Yes      | Your Arcbeam API key                                              |
    | `project_id`  | string | No       | Specific project to send traces to (uses default if not provided) |
    | `environment` | string | No       | Environment tag (e.g., `"production"`, `"dev"`)                   |
    | `run_id`      | string | No       | Run name (e.g., git commit, code version, eval test, etc)         |
  </Tab>
</Tabs>

## Self-Hosted Configuration

If you're running Arcbeam on your own infrastructure, configure the connector to send traces to your self-hosted instance by setting the `base_url` parameter:

```python theme={null}
from arcbeam_connector.langchain.connector import ArcbeamLangConnector

connector = ArcbeamLangConnector(
    base_url="https://your-domain.com",  # Your self-hosted instance URL
    api_key="your-api-key-here",
)
connector.init()
```

## Security Best Practices

<AccordionGroup>
  <Accordion title="Store API Keys Securely" icon="key">
    Never hardcode API keys in your source code. Use environment variables:

    ```bash theme={null}
    export ARCBEAM_API_KEY=sk-...
    ```

    <Tip>
      Use a secrets manager like AWS Secrets Manager, HashiCorp Vault, or 1Password for production deployments.
    </Tip>
  </Accordion>

  <Accordion title="Use Different Keys Per Environment" icon="layer-group">
    Create separate API keys for each environment:

    | Environment     | Purpose                | Benefits                                               |
    | --------------- | ---------------------- | ------------------------------------------------------ |
    | **Development** | Local testing          | Safe experimentation without affecting production data |
    | **Staging**     | Pre-production testing | Validate changes before production deployment          |
    | **Production**  | Live applications      | Isolated credentials for production security           |

    This makes it easier to track usage and revoke access if needed.
  </Accordion>
</AccordionGroup>

## Performance Considerations

<Info>
  **Asynchronous Transmission** - Traces are sent asynchronously, so they don't block your application. The connector uses a background thread to batch and send traces.
</Info>

<Info>
  **Network Failures** - If the Arcbeam platform is unreachable, traces are queued and retried automatically. Your application continues running normally.
</Info>

<Warning>
  **Data Privacy** - Traces contain your prompts, responses, and metadata. If you're handling sensitive data:

  * Use self-hosted Arcbeam in your own infrastructure
  * Review what data is being sent (see [What Gets Captured](#what-gets-captured))
  * Consider filtering sensitive information before sending
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Python Guide" icon="python" href="/v0/integrations/ai-frameworks/langchain">
    Detailed guide with LangChain and LangGraph examples
  </Card>

  <Card title="Observability" icon="list" href="/v0/core-concepts/observability">
    Learn what data is captured in traces
  </Card>

  <Card title="Environments" icon="layer-group" href="/v0/deployment/environments">
    Organize traces by environment
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/v0/deployment/troubleshooting">
    Fix common issues
  </Card>
</CardGroup>