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

# Overview

> Attribute network cost to the callers behind it, using a header your clients already send

Request header attribution lets you put a name on the network traffic your
services generate. Your client adds an `X-CostGraph-<key>` header to its outgoing HTTP requests.
CostGraph attributes the bytes and cost of each request to that header's value. You don't need a proxy or SDK. The
[agent](/costgraph/header-attribution/usage#enable-capture) reads the header as the request leaves the process.

## Why network cost is hard to attribute

Network spend is one of the hardest lines on a cloud bill to explain. The bill
tells you how much traffic crossed a zone or region or went out to the internet.
It does not tell you which customer, feature, or team caused it.

Labels on the workload don't solve this. One service often handles requests for
many tenants, many jobs, and many features over the same connections. A pod
label like `team=payments` is right for the pod, but it can't separate the call
made for one customer from the call made for another.

The one place that context does exist is the request itself. Applications
already know who they're calling on behalf of, and they usually carry that in a
header.

## What request header attribution is

Request header attribution turns that context into a cost dimension. Any request
header whose name starts with `X-CostGraph-` becomes a tag on that request:

```http theme={null}
GET /v1/objects/report.csv HTTP/1.1
Host: storage.internal
X-CostGraph-Tenant: acme
X-CostGraph-Feature: export
```

This request is attributed to `tenant = acme` and `feature = export`. Its request
and response bytes, and the network cost they incur, are counted under those
values.

Attribution is **per request**, not per connection. Two requests on the same
keep-alive connection can carry different values, and each one is counted under
its own.

## Header tags vs. workload labels

Header tags sit alongside the labels CostGraph already knows about your
workloads. They answer a different question.

| | Workload labels | Request header tags |
| - | - | - |
| Granularity | Per container or pod | Per HTTP request |
| Where the value comes from | Your orchestrator or cloud account | Your application, at request time |
| To change one | Redeploy or relabel the workload | Change the header the client sends |
| Separates tenants sharing one service | No | Yes |
| Needs application changes | No | Yes, the client must send the header |

## When to use it

Use request header attribution when the workload is the wrong unit for the
question you're asking. Typical cases are:

* Per-tenant or per-customer network cost from a shared multi-tenant service.
* Cost of a feature, job, or pipeline stage that runs inside a larger process.
* Chargeback for callers of a shared internal API, where every caller's traffic
  comes from the same gateway.

## How it works

The [CostGraph agent](/costgraph/agent) uses eBPF to observe TLS and plaintext
HTTP traffic in processes on the node. It reads plaintext at the point where the
client's TLS library encrypts it, so it sees HTTPS requests without terminating
TLS or holding any keys.

For each outgoing request from a supported client, the agent:

1. Reads the request headers and keeps only those that start with
   `X-CostGraph-`. All other headers and all request and response bodies are
   ignored.
2. Turns each matching header into a tag key and value.
3. Measures the full request and response size, including headers and body.
4. Ties the request to the container that sent it and to the connection's
   destination.

CostGraph then prices the bytes by where the destination sits, such as same zone,
cross zone, or internet. You can group and filter the result by any tag key.

<Note>
  The agent only reads headers. It never adds, changes, or removes headers on
  your requests, and it never stores request or response bodies.
</Note>

## Next steps

<Card title="Usage" icon="route" href="/costgraph/header-attribution/usage">
  Check the requirements, enable capture, send your first header, and read the
  results on the Network page.
</Card>

<Card title="Virtual tags" icon="tags" href="/costgraph/virtual-tags/overview">
  Attribute spend by resource rather than by request, with rules evaluated
  against your cost data.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.