asyncapi: 2.6.0 info: title: Fluentd Forward Protocol description: >- The Fluentd Forward Protocol is a binary MessagePack-based protocol used to transport event streams between Fluentd nodes, Fluent Bit agents, and compatible forwarders over TCP or TLS. It supports multiple transport modes including Message, Forward, PackedForward, and CompressedPackedForward, as well as optional SASL-style authentication and heartbeat mechanisms for connection health checking. version: '1.0.0' contact: name: Fluentd Community url: https://www.fluentd.org/community/ license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0 externalDocs: description: Forward Protocol Specification v1 url: https://github.com/fluent/fluentd/wiki/Forward-Protocol-Specification-v1 servers: fluentd: url: 'tcp://localhost:24224' protocol: tcp description: >- Default Fluentd forward input listener. TLS variants use the same port with a TLS-wrapped connection when tls_enable is set to true in the in_forward plugin configuration. channels: /forward: description: >- The Forward Protocol channel transports Fluentd event streams from upstream forwarders or agents to a downstream Fluentd aggregator. Messages are serialized as MessagePack arrays and sent over a persistent TCP connection. publish: operationId: forwardEvents summary: Forward one or more log events to a Fluentd aggregator description: >- Sends log events from a Fluentd forwarder or Fluent Bit agent to an aggregating Fluentd instance. The message format depends on the transport mode selected by the sender. The Mode mode sends a single event; Forward mode sends multiple events sharing a tag; PackedForward sends events pre-serialized as a MessagePack byte stream; CompressedPackedForward adds gzip compression on top of PackedForward. message: oneOf: - $ref: '#/components/messages/MessageMode' - $ref: '#/components/messages/ForwardMode' - $ref: '#/components/messages/PackedForwardMode' - $ref: '#/components/messages/CompressedPackedForwardMode' /heartbeat: description: >- UDP heartbeat channel used for keepalive and connection health checking between a forwarder and its upstream aggregator. publish: operationId: sendHeartbeat summary: Send a heartbeat packet description: >- A forwarder periodically sends a UDP heartbeat packet (a single null byte) to the aggregator. The aggregator echoes it back to confirm the connection is alive. message: $ref: '#/components/messages/Heartbeat' components: securitySchemes: sharedKeyAuth: type: httpApiKey in: header name: Authorization description: >- Optional SASL-style shared key authentication. The forwarder presents a nonce-based HMAC challenge response derived from a pre-shared key configured in both the out_forward and in_forward plugins. messages: MessageMode: name: MessageMode title: Message Mode Event summary: A single log event with tag, timestamp, and record description: >- The simplest Forward Protocol message. Encodes a single event as a 3-element or 4-element MessagePack array: [tag, time, record] or [tag, time, record, option]. Used when the sender has one event to transmit. contentType: application/msgpack payload: $ref: '#/components/schemas/MessageModePayload' ForwardMode: name: ForwardMode title: Forward Mode Event summary: A batch of log events sharing a single tag description: >- Encodes multiple events under one tag as a 3-element or 4-element MessagePack array: [tag, entries, option]. Each entry is a 2-element array [time, record]. Efficient when the sender batches many events for the same tag before flushing. contentType: application/msgpack payload: $ref: '#/components/schemas/ForwardModePayload' PackedForwardMode: name: PackedForwardMode title: Packed Forward Mode Event summary: >- A batch of pre-serialized log events as a raw MessagePack byte stream description: >- Encodes events as a 3-element or 4-element array [tag, entries, option] where entries is a raw binary blob of concatenated MessagePack [time, record] pairs. This avoids double-encoding overhead and is the default mode used by Fluentd's out_forward plugin. contentType: application/msgpack payload: $ref: '#/components/schemas/PackedForwardModePayload' CompressedPackedForwardMode: name: CompressedPackedForwardMode title: Compressed Packed Forward Mode Event summary: A gzip-compressed packed forward batch description: >- The same as PackedForwardMode but the entries binary blob is additionally gzip-compressed. The option map must include {"compressed":"gzip"} to signal the encoding to the receiver. Reduces bandwidth for high-volume log pipelines. contentType: application/msgpack payload: $ref: '#/components/schemas/CompressedPackedForwardModePayload' Heartbeat: name: Heartbeat title: Heartbeat Packet summary: A UDP keepalive packet description: >- A single null byte (0x00) sent over UDP by a forwarder to the aggregator's heartbeat port (default: same as TCP port). The aggregator echoes the packet back to confirm reachability. contentType: application/octet-stream payload: type: string description: Single null byte heartbeat payload. schemas: MessageModePayload: type: array description: >- A MessagePack array representing a single Fluentd event in Message mode: [tag, time, record] or [tag, time, record, option]. prefixItems: - type: string description: The Fluentd routing tag. - $ref: '#/components/schemas/EventTime' - $ref: '#/components/schemas/Record' - $ref: '#/components/schemas/OptionMap' minItems: 3 maxItems: 4 ForwardModePayload: type: array description: >- A MessagePack array representing a batch of Fluentd events in Forward mode: [tag, entries, option]. prefixItems: - type: string description: The Fluentd routing tag shared by all events in the batch. - type: array description: Array of [time, record] entry pairs. items: $ref: '#/components/schemas/Entry' - $ref: '#/components/schemas/OptionMap' minItems: 2 maxItems: 3 PackedForwardModePayload: type: array description: >- A MessagePack array representing a packed batch: [tag, entries_bytes, option]. entries_bytes is a raw binary sequence of MessagePack-encoded [time, record] pairs. prefixItems: - type: string description: The Fluentd routing tag. - type: string contentEncoding: binary description: >- Raw binary blob of concatenated MessagePack-encoded [time, record] pairs. - $ref: '#/components/schemas/OptionMap' minItems: 2 maxItems: 3 CompressedPackedForwardModePayload: type: array description: >- Same as PackedForwardModePayload but the entries binary blob is gzip-compressed. The option map must contain {"compressed":"gzip"}. prefixItems: - type: string description: The Fluentd routing tag. - type: string contentEncoding: binary description: Gzip-compressed binary blob of packed MessagePack entries. - $ref: '#/components/schemas/OptionMap' minItems: 2 maxItems: 3 Entry: type: array description: A single event entry consisting of a timestamp and a record. prefixItems: - $ref: '#/components/schemas/EventTime' - $ref: '#/components/schemas/Record' minItems: 2 maxItems: 2 EventTime: description: >- Event timestamp. Can be a Unix epoch integer (seconds) or a Fluentd EventTime MessagePack extension type that carries both seconds and nanoseconds for sub-second precision. oneOf: - type: integer description: Unix epoch time in seconds. example: 1700000000 - type: object description: >- Fluentd EventTime extension (MessagePack ext type 0). Contains seconds and nanoseconds fields for nanosecond-precision timestamps. properties: seconds: type: integer description: Seconds since Unix epoch. nanoseconds: type: integer description: Nanosecond component of the timestamp. Record: type: object description: >- The log record payload. An arbitrary key-value map where keys are strings and values can be any MessagePack-compatible type. The fields are defined by the emitting application or plugin. additionalProperties: true OptionMap: type: object description: >- Optional metadata map attached to a Forward Protocol message. Can carry acknowledgement chunk IDs, compression hints, and size hints. properties: chunk: type: string description: >- A unique base64-encoded identifier for this message batch used for at-least-once acknowledgement. The receiver sends back {"ack":chunk} to confirm delivery. compressed: type: string description: >- Indicates the compression algorithm applied to packed entries. Currently only 'gzip' is supported. enum: - gzip size: type: integer description: >- The number of records in the batch. Used as a hint by the receiver to pre-allocate buffers.