Fluentd Forward Protocol

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.