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

# Monitor Anthropic Usage & Cost

> Monitor Anthropic API token consumption, feature usage, and cost attribution in real time using a custom OpenTelemetry collector and Honeycomb Board Templates.

Monitor your Anthropic API usage and costs in real-time by collecting detailed metrics and logs with a custom OpenTelemetry collector. This integration provides comprehensive visibility into token consumption, feature usage, and cost attribution across models, workspaces, and API keys.

## Overview

The Anthropic Usage & Cost Monitoring integration uses an OpenTelemetry receiver to collect detailed usage metrics and cost data from the Anthropic Admin API, transforming them into structured telemetry for monitoring and cost tracking in Honeycomb.

**What's Collected:**

* **Usage Metrics** (minute-level granularity): Token consumption (input, output, cache), feature usage (web searches), grouped by model, tier, workspace, and API key
* **Cost Data** (daily logs): Detailed cost breakdowns with workspace attribution and human-readable descriptions

## Prerequisites

* [Anthropic Admin API key](https://console.anthropic.com/settings/keys) with organization admin access
* [OpenTelemetry Collector Builder](https://github.com/open-telemetry/opentelemetry-collector/releases) v0.130.0+
* Go 1.23+ (for building custom collector)

## Custom Collector Setup

The Anthropic Usage Receiver is designed to be integrated into a custom OpenTelemetry Collector using the OpenTelemetry Collector Builder (OCB).

<Steps titleSize="h3">
  <Step title="Install OpenTelemetry Collector Builder">
    Download the appropriate OCB binary for your platform:

    ```bash theme={}
    # For Linux/macOS (adjust version and platform as needed)
    curl -L -O https://github.com/open-telemetry/opentelemetry-collector/releases/download/cmd%2Fbuilder%2Fv0.131.0/ocb_0.131.0_linux_amd64
    chmod +x ocb_0.131.0_linux_amd64
    mv ocb_0.131.0_linux_amd64 ocb
    ```
  </Step>

  <Step title="Create Builder Configuration">
    Create a `builder-config.yaml` file that includes the Anthropic Usage Receiver:

    ```yaml theme={}
    dist:
      name: otelcol-anthropic
      description: Custom OpenTelemetry Collector with Anthropic Usage Receiver
      output_path: ./dist
      otelcol_version: 0.131.0

    exporters:
      - gomod: go.opentelemetry.io/collector/exporter/debugexporter v0.131.0
      - gomod: go.opentelemetry.io/collector/exporter/otlpexporter v0.131.0
      - gomod: go.opentelemetry.io/collector/exporter/otlphttpexporter v0.131.0

    processors:
      - gomod: go.opentelemetry.io/collector/processor/batchprocessor v0.131.0
      - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/resourceprocessor v0.131.0

    receivers:
      - gomod: go.opentelemetry.io/collector/receiver/otlpreceiver v0.131.0
      - gomod: github.com/honeycombio/anthropic-usage-receiver/anthropicusagereceiver v0.1.0

    extensions:
      - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/healthcheckextension v0.131.0
      - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/storage/filestorage v0.131.0
    ```
  </Step>

  <Step title="Build Custom Collector">
    ```bash theme={}
    ./ocb --config builder-config.yaml
    ```

    This generates a custom collector binary in the `./dist` directory.
  </Step>
</Steps>

## Deployment Options

### Stateless Deployment

For environments where persistence isn't required (e.g., short-lived containers, testing):

```yaml theme={}
receivers:
  anthropicusage:
    admin_api_key: ${env:ANTHROPIC_ADMIN_API_KEY}
    endpoint: https://api.anthropic.com
    collection_interval: 1m
    usage:
      enabled: true
      bucket_width: 1m
      group_by: [model, service_tier, context_window, workspace_id, api_key_id]
    cost:
      enabled: true
      collection_interval: 24h
      bucket_width: 1d
      group_by: [workspace_id, description]

exporters:
  otlp_http:
    endpoint: https://api.honeycomb.io:443
    headers:
      "x-honeycomb-team": "${env:HONEYCOMB_API_KEY}"

service:
  pipelines:
    metrics:
      receivers: [anthropicusage]
      processors: [batch]
      exporters: [otlp_http]
    logs:
      receivers: [anthropicusage]
      processors: [batch]
      exporters: [otlp_http]
```

### Stateful Deployment

For production environments where checkpoint persistence is important to prevent data loss during restarts:

```yaml theme={}
extensions:
  file_storage:
    directory: /var/lib/otel/anthropic-storage
    timeout: 10s

receivers:
  anthropicusage:
    admin_api_key: ${env:ANTHROPIC_ADMIN_API_KEY}
    endpoint: https://api.anthropic.com
    collection_interval: 1m
    storage: file_storage  # Enable checkpoint persistence
    usage:
      enabled: true
      bucket_width: 1m
      group_by: [model, service_tier, context_window, workspace_id, api_key_id]
    cost:
      enabled: true
      collection_interval: 24h
      bucket_width: 1d
      group_by: [workspace_id, description]
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 60s
      max_elapsed_time: 5m

exporters:
  otlp_http:
    endpoint: https://api.honeycomb.io:443
    headers:
      "x-honeycomb-team": "${env:HONEYCOMB_API_KEY}"

processors:
  batch:
    timeout: 10s
    send_batch_size: 512

service:
  extensions: [file_storage]
  pipelines:
    metrics:
      receivers: [anthropicusage]
      processors: [batch]
      exporters: [otlp_http]
    logs:
      receivers: [anthropicusage]
      processors: [batch]
      exporters: [otlp_http]
```

<Tip>
  **Stateful vs Stateless:**

  * **Stateful**: Maintains checkpoint state across restarts, preventing data loss and duplicate collection. Recommended for production.
  * **Stateless**: Simpler setup but may miss data during restarts. Suitable for testing or environments with external state management.
</Tip>

### Run the Collector

```bash theme={}
export ANTHROPIC_ADMIN_API_KEY="sk-ant-admin-..."
export HONEYCOMB_API_KEY="your-honeycomb-api-key"
./dist/otelcol-anthropic --config=config.yaml
```

## Using the Anthropic Usage Board Template

Once your data is flowing into Honeycomb, use the pre-built Anthropic Usage & Cost Monitoring Board Template to instantly visualize your usage and costs:

1. Navigate to **Boards** in the Honeycomb UI
2. Select **Templates** or **Create Boards** → **From Template**
3. Choose **Anthropic Usage & Cost Monitoring** template
4. Review the template preview with your data
5. If needed, map any fields in the **Setup** view to match your data structure
6. Select **Use Template** to create your board

The template includes pre-configured visualizations for:

* Token usage trends and patterns
* Cost monitoring and attribution
* Cache utilization analysis
* Usage distribution across models and workspaces

<Tip>
  The board template automatically works with data from the Anthropic Usage Receiver. If some queries show "Unable to display", verify your collector is running and data is flowing to Honeycomb.
</Tip>

## Configuration Reference

### Usage Metrics

| Metric                                        | Description                                       |
| --------------------------------------------- | ------------------------------------------------- |
| `anthropic.usage.input_tokens`                | Number of uncached input tokens consumed          |
| `anthropic.usage.output_tokens`               | Number of output tokens generated                 |
| `anthropic.usage.cache_creation.ephemeral_1h` | Tokens used for 1-hour ephemeral cache creation   |
| `anthropic.usage.cache_creation.ephemeral_5m` | Tokens used for 5-minute ephemeral cache creation |
| `anthropic.usage.cache_read_input_tokens`     | Input tokens read from cache                      |
| `anthropic.usage.web_search_requests`         | Number of web search requests                     |

### Cost Metrics

| Metric                  | Description                                                          |
| ----------------------- | -------------------------------------------------------------------- |
| `anthropic.cost.amount` | Cost amount in minor currency units (e.g., fractional cents for USD) |

### Key Attributes

| Attribute        | Description                                                 | Example                                                            |
| ---------------- | ----------------------------------------------------------- | ------------------------------------------------------------------ |
| `model`          | Claude model used                                           | `claude-3-7-sonnet-20250219`, `claude-opus-4-20250514`             |
| `service_tier`   | API service tier                                            | `standard`, `batch`, `priority`                                    |
| `context_window` | Context window size                                         | `0-200k`, `200k-1M`                                                |
| `workspace_id`   | Anthropic workspace identifier (null for default workspace) | `wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ`                                  |
| `api_key_id`     | API key identifier (null for workbench usage)               | `apikey_01Rj2N8SVvo6BePZj99NhmiT`                                  |
| `description`    | Human-readable cost description                             | `Claude Sonnet 4 Usage - Input Tokens, Cache Write 1 Hour - Batch` |
| `currency`       | ISO 4217 currency code                                      | `USD`                                                              |

## Advanced Configuration

### Filtering Data Collection

Limit data collection to specific models, tiers, or workspaces:

```yaml theme={}
receivers:
  anthropicusage:
    usage:
      # Collect only specific models
      models: ["claude-3-7-sonnet-20250219", "claude-3-haiku-20240307"]
      # Filter by service tiers
      service_tiers: ["standard", "priority"]
      # Filter by context window sizes
      context_window: ["0-200k", "200k-1M"]
      # Filter by workspaces
      workspace_ids: ["wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ", "wrkspc_013jtUYxRJqPEXaTUxQVmmJa"]
      # Customize grouping
      group_by: [model, service_tier, context_window, workspace_id]
```

### Multiple Exporters

Send data to multiple destinations:

```yaml theme={}
service:
  pipelines:
    metrics:
      receivers: [anthropicusage]
      processors: [batch]
      exporters: [otlp, prometheus, debug]
    logs:
      receivers: [anthropicusage]
      processors: [batch]
      exporters: [otlp, debug]
```

## Troubleshooting

### Common Issues

**No data appearing in Honeycomb:**

* Verify your Anthropic Admin API key has proper permissions
* Check collector logs for authentication errors
* Ensure your Honeycomb API key is configured correctly

**Missing cost data:**

* Cost data is only available at daily granularity
* Ensure `cost.enabled: true` in your configuration
* Check that your Admin API key has cost visibility permissions

**Checkpoint persistence not working:**

* Verify the storage directory is writable
* Check that the file\_storage extension is properly configured
* Ensure the storage extension is referenced in the service section

**High API usage:**

* Increase `collection_interval` to reduce API call frequency (minimum recommended: 1 minute)
* Use filtering to collect only necessary data
* Monitor the `anthropic.scraper.up` metric for health status
* Note: Usage and cost data appears within 5 minutes of API request completion

**Rate limiting:**

* The API is designed for polling once per minute maximum
* Reduce polling frequency if you encounter rate limit errors
* Consider caching results for frequently updated dashboards

### Getting Help

* View detailed configuration options in the [Anthropic Usage Receiver repository](https://github.com/honeycombio/anthropic-usage-receiver)
* Check the [OpenTelemetry Collector documentation](https://opentelemetry.io/docs/collector/) for general collector issues
* For Honeycomb-specific questions, consult the [Honeycomb documentation](/troubleshoot/) or contact support