# KafkaJSRequestTimeoutErrorMetadata

**Kind:** Interface

**Source:** [`packages/microservices/external/kafka.interface.ts`](https://github.com/nestjs/nest/blob/master/packages/microservices/external/kafka.interface.ts#L1304)

**Part of:** [Microservices](subsystem-packages-microservices)

`KafkaJSRequestTimeoutErrorMetadata` describes diagnostic timing and routing details for a KafkaJS request that exceeded its timeout. It captures the target broker, client identity, correlation ID, and timestamps needed to calculate how long the request remained pending.

## Properties

| Property | Type |
|---|---|
| `broker` | `string` |
| `clientId` | `string` |
| `correlationId` | `number` |
| `createdAt` | `number` |
| `sentAt` | `number` |
| `pendingDuration` | `number` |

## Diagram

```mermaid
graph LR
  Client[Kafka Client] -->|request| Broker[Kafka Broker]
  Client --> Metadata[KafkaJSRequestTimeoutErrorMetadata]
  Metadata --> B[broker: string]
  Metadata --> C[clientId: string]
  Metadata --> CID[correlationId: number]
  Metadata --> CA[createdAt: number]
  Metadata --> SA[sentAt: number]
  Metadata --> PD[pendingDuration: number]
  Broker -->|timeout| Error[Request Timeout Error]
  Metadata --> Error
```

## Usage

```ts
import type { KafkaJSRequestTimeoutErrorMetadata } from './kafka.interface';

function logRequestTimeout(
  metadata: KafkaJSRequestTimeoutErrorMetadata,
): void {
  console.error('Kafka request timed out', {
    broker: metadata.broker,
    clientId: metadata.clientId,
    correlationId: metadata.correlationId,
    pendingDurationMs: metadata.pendingDuration,
    createdAt: new Date(metadata.createdAt).toISOString(),
    sentAt: new Date(metadata.sentAt).toISOString(),
  });
}

const timeoutMetadata: KafkaJSRequestTimeoutErrorMetadata = {
  broker: 'localhost:9092',
  clientId: 'orders-service',
  correlationId: 42,
  createdAt: Date.now() - 10_000,
  sentAt: Date.now() - 9_500,
  pendingDuration: 9_500,
};

logRequestTimeout(timeoutMetadata);
```

## AI Coding Instructions

- Treat `createdAt`, `sentAt`, and `pendingDuration` as millisecond-based numeric timestamps/durations.
- Preserve the original `broker`, `clientId`, and `correlationId` values when wrapping or rethrowing Kafka timeout errors.
- Use this metadata for structured logging, tracing attributes, and timeout diagnostics rather than user-facing error messages.
- Do not assume `pendingDuration` is equivalent to total application processing time; it represents the Kafka request's pending duration.