# Tracing Headers

K2K can enrich each replicated record with metadata about its origin and the replication process. This information is added as standard Kafka record headers, making it available to downstream systems for data lineage tracking, debugging, or advanced observability.

The feature is controlled by two configuration blocks:

* `features.tracingHeaders` enables/disables specific headers
* `tracing.headers` customizes the header names.

## **Configuration Parameters**

Tracing headers can be enabled/disabled all at once by providing specifying `enabled` or `disabled` as the value for `tracingHeaders` .

Alternatively, headers can be enabled/disabled individually by providing the one or more of the following properties as the value of `features.tracingHeaders`

| Property    | Description                                                                                                   |
| ----------- | ------------------------------------------------------------------------------------------------------------- |
| `partition` | When set to `enabled`, adds a header containing the record's original partition number from the source topic. |
| `offset`    | When set to `enabled`, adds a header containing the record's original offset from the source partition.       |
| `topic`     | When set to `enabled`, adds a header containing the record's original source topic name.                      |
| `pipeline`  | When set to `enabled`, adds a header containing the K2K application name (pipeline).                          |

The names of the headers used can be customized using `tracing.headers` :

| Property    | Description                                         | Default Name    |
| ----------- | --------------------------------------------------- | --------------- |
| `partition` | Overrides the name for the source partition header. | `k2k_partition` |
| `offset`    | Overrides the name for the source offset header.    | `k2k_offset`    |
| `topic`     | Overrides the name for the source topic header.     | `k2k_topic`     |
| `pipeline`  | Overrides the name for the pipeline header.         | `k2k_pipeline`  |

## **Examples**

The following example enables all tracing headers:

```yaml
# ---------------------------------------------------
# K2K Configuration for Tracing Headers
# ---------------------------------------------------

# 1. Enable the desired headers under the 'features' block.
features:
  tracingHeaders: enabled
# 2. Optionally, customize the names of the enabled headers.
tracing:
  headers:
    # The partition header will use its default name ('k2k.source.partition').
    # The offset header name is overridden to 'replication_offset'.
    offset: "replication_offset"
```

***

The following example configures K2K to add headers for the source partition and offset, and it provides a custom name for the offset header.

```yaml
# ---------------------------------------------------
# K2K Configuration for Tracing Headers
# ---------------------------------------------------

# 1. Enable the desired headers under the 'features' block.
features:
  tracingHeaders:
    # Enable the source partition and offset headers.
    partition: enabled
    offset: enabled
    # The 'topic' and 'pipeline' headers will remain disabled.
    # topic: disabled
    # pipeline: disabled

# 2. Optionally, customize the names of the enabled headers.
tracing:
  headers:
    # The partition header will use its default name ('k2k.source.partition').
    # The offset header name is overridden to 'replication_offset'.
    offset: "replication_offset"
```

Resulting Record Headers:

A record processed with the configuration above would contain the following headers (example values):

| Header Name          | Example Value |
| -------------------- | ------------- |
| `k2k_partition`      | `5`           |
| `replication_offset` | `123456`      |