Cloud
Also in Self-Managed

redpanda_common

This component is deprecated and will be removed in a future version.

Consumes data from a Redpanda (Kafka) broker, using credentials defined in a common top-level redpanda config block.

This input is deprecated as of version 4.68.0. Use the redpanda input instead. When you omit its connection fields, the redpanda input connects using the same top-level redpanda config block.

When a consumer group is specified this input consumes one or more topics, and partitions automatically balance across any other connected clients with the same consumer group. When a consumer group is not specified, topics can either be consumed in their entirety or with explicit partitions.

Delivery Guarantees

When using consumer groups, the offsets of "delivered" records are committed automatically and continuously, and in the event of restarts these committed offsets are used to resume from where the input left off. Redpanda Connect guarantees at least once delivery by ensuring that records are only considered to be delivered when all configured outputs that the record is routed to have confirmed delivery.

Ordering

To preserve ordering of topic partitions, records consumed from each partition are processed and delivered in the order that they are received, and only one batch of records of a given partition is ever processed at a time. This means that parallel processing can only occur when multiple topic partitions are being consumed, but ensures that data is processed in a sequential order as determined from the source partition.

However, one way in which the order of records can be mixed is when delivery errors occur and error handling mechanisms kick in. Redpanda Connect always leans towards at least once delivery unless instructed otherwise, and this includes reattempting delivery of data when the ordering of that data can no longer be guaranteed.

For example, a batch of records may have been sent to an output broker and only a subset of records were delivered. In this case Redpanda Connect by default reattempts to deliver the records that failed, even though these failed records may have come before records that were previously delivered successfully.

To avoid this scenario you must specify in your configuration an alternative way to handle delivery errors in the form of a fallback output. It is good practice to also disable the field auto_retry_nacks by setting it to false when you’ve added an explicit fallback output as this improves the throughput of your pipeline. For example, the following config avoids ordering issues by specifying a fallback output into a DLQ topic, which is also retried indefinitely as a way to apply back pressure during connectivity issues:

output:
  fallback:
    - redpanda_common:
        topic: foo
    - retry:
        output:
          redpanda_common:
            topic: foo_dlq

Batching

Records are processed and delivered from each partition in batches as received from brokers. These batch sizes are therefore dynamically sized in order to optimise throughput, but can be tuned with the config fields fetch_max_bytes, fetch_max_partition_bytes, and max_yield_batch_bytes. Batches can be further broken down using the split processor.

Metrics

When a consumer group is set, this input emits a redpanda_lag metric with topic and partition labels for each consumed topic. The metric records the number of produced messages that the consumer group has not yet read from each topic partition.

Metadata

This input adds the following metadata fields to each message:

  • kafka_key

  • kafka_topic

  • kafka_partition

  • kafka_offset

  • kafka_lag

  • kafka_timestamp_ms

  • kafka_timestamp_unix

  • kafka_tombstone_message

  • All record headers

If you need to move topic data between Redpanda clusters or other Apache Kafka clusters, consider using the redpanda input and output instead.

  • Common

  • Advanced

input:
  label: ""
  redpanda_common:
    topics: [] # No default (optional)
    regexp_topics_include: [] # No default (optional)
    regexp_topics_exclude: [] # No default (optional)
    transaction_isolation_level: read_uncommitted
    consumer_group: "" # No default (optional)
    auto_replay_nacks: true
input:
  label: ""
  redpanda_common:
    topics: [] # No default (optional)
    regexp_topics_include: [] # No default (optional)
    regexp_topics_exclude: [] # No default (optional)
    rack_id: ""
    instance_id: ""
    rebalance_timeout: 45s
    session_timeout: 1m
    heartbeat_interval: 3s
    start_offset: earliest
    fetch_max_bytes: 50MiB
    fetch_max_wait: 5s
    fetch_min_bytes: 1B
    fetch_max_partition_bytes: 1MiB
    transaction_isolation_level: read_uncommitted
    consumer_group: "" # No default (optional)
    commit_period: 5s
    partition_buffer_bytes: 1MB
    topic_lag_refresh_period: 5s
    max_yield_batch_bytes: 32KB
    auto_replay_nacks: true
    timely_nacks_maximum_wait: "" # No default (optional)

Pipeline example

This data pipeline reads data from topic_A and topic_B on a Redpanda cluster, and then writes the data to topic_C on the same cluster. The cluster details are configured within the redpanda configuration block, so you only need to configure them once. This is a useful feature when you have multiple inputs and outputs in the same data pipeline that need to connect to the same cluster.

input:
  redpanda_common:
    topics: [ topic_A, topic_B ]

output:
  redpanda_common:
    topic: topic_C
    key: ${! @id }

redpanda:
  seed_brokers: [ "127.0.0.1:9092" ]
  tls:
    enabled: true
  sasl:
    - mechanism: SCRAM-SHA-512
      password: bar
      username: foo

Fields

auto_replay_nacks

Whether to automatically replay rejected messages (negative acknowledgements, or nacks) at the output level. If the cause of rejections persists, leaving this option enabled can result in back pressure.

Set auto_replay_nacks to false to delete rejected messages. Disabling auto replays can greatly improve memory efficiency of high throughput streams, as the original shape of the data is discarded immediately upon consumption and mutation.

Type: bool

Default: true

commit_period

The period of time between each commit of the current partition offsets to the consumer group. Offsets are always committed during shutdown.

Type: string

Default: 5s

consumer_group

An optional consumer group. When you specify this value:

  • The partitions of any topics specified in the topics field are automatically distributed across consumers that share the consumer group.

  • Partition offsets are automatically committed and resumed under this name.

Consumer groups are not supported when you specify explicit partitions to consume from in the topics field.

Type: string

fetch_max_bytes

The maximum number of bytes that a broker tries to send during a fetch.

If individual records are larger than the fetch_max_bytes value, brokers still send them.

This field is equivalent to the Java setting fetch.max.bytes.

Type: string

Default: 50MiB

fetch_max_partition_bytes

The maximum number of bytes that are consumed from a single partition in a fetch request. This field is equivalent to the Java setting fetch.max.partition.bytes.

If a single batch is larger than the fetch_max_partition_bytes value, the batch is still sent so that the client can make progress.

Type: string

Default: 1MiB

fetch_max_wait

The maximum period of time a broker can wait for a fetch response to reach the required minimum number of bytes (fetch_min_bytes). This field is equivalent to the Java setting fetch.max.wait.ms.

Type: string

Default: 5s

fetch_min_bytes

The minimum number of bytes that a broker tries to send during a fetch. This field is equivalent to the Java setting fetch.min.bytes.

Type: string

Default: 1B

heartbeat_interval

When you specify a consumer_group, heartbeat_interval sets how frequently a consumer group member should send heartbeats to Apache Kafka. Apache Kafka uses heartbeats to make sure that a group member’s session is active.

This value must be lower than session_timeout, and should be no higher than one-third of session_timeout.

This field is equivalent to the Java heartbeat.interval.ms setting and accepts Go duration format strings such as 10s or 2m.

Type: string

Default: 3s

instance_id

When you specify a consumer_group, set instance_id to define the group’s static membership, which can prevent unnecessary rebalances during reconnections. The value must be unique per consumer within the group.

When you assign an instance ID, the client does not leave the consumer group when it closes. To remove the client from the group, you must use an external admin command on behalf of the instance ID.

Type: string

Default: ""

max_yield_batch_bytes

The maximum size (in bytes) for each batch yielded by this input. This value must be less than or equal to the partition_buffer_bytes. If using Redpanda output, this value should not be greater than the max_message_bytes option value (1MB by default), and for high-throughput scenarios they should be equal.

Type: string

Default: 32KB

partition_buffer_bytes

A buffer size (in bytes) for each consumed partition, which allows the internal queuing of records before they are flushed. Increasing this value may improve throughput but results in higher memory utilization.

Each buffer can grow slightly beyond this value.

Type: string

Default: 1MB

rack_id

A rack specifies where the client is physically located, and changes fetch requests to consume from the closest replica as opposed to the leader replica.

Type: string

Default: ""

rebalance_timeout

When you specify a consumer_group, rebalance_timeout sets how long consumer group members can take to complete their work and commit offsets after a rebalance has begun. The time that a member takes to detect the rebalance (from a heartbeat) counts against this timeout. This field accepts Go duration format strings such as 100ms, 1s, or 5s.

Type: string

Default: 45s

regexp_topics_exclude[]

A list of regular expression patterns for excluding topics when regex mode is enabled (using regexp_topics_include or the deprecated regexp_topics boolean). Topics matching any of these patterns will be excluded from consumption, even if they match include patterns.

Each pattern is a full regular expression evaluated against the complete topic name. Patterns are not anchored by default, so use ^ and $ for exact matching. Exclude patterns are applied after include patterns, providing fine-grained control over topic selection.

Example: regexp_topics_exclude: ["^_", ".-temp$", ".-test.*"] excludes topics starting with underscore, ending with -temp, or containing -test.

Type: array<string>

regexp_topics_include[]

A list of regular expression patterns for matching topics to consume from. When specified, the client will periodically refresh the list of matching topics based on the metadata_max_age interval.

Each pattern is a full regular expression evaluated against the complete topic name. Patterns are not anchored by default, so logs_. matches my-logs_events and logs_errors. Use ^logs_.$ to match only topics starting with logs_.

This field enables regex mode (replacing the deprecated regexp_topics boolean) and cannot be used together with explicit topics lists. Use regexp_topics_exclude to filter out specific patterns from the matched topics.

Example: regexp_topics_include: ["events_.", "logs_."] consumes from all topics starting with events_ or logs_.

Type: array<string>

# Examples:
regexp_topics_include:
  - logs_.*
  - metrics_.*

# ---

regexp_topics_include:
  - "events_[0-9]+"

session_timeout

When you specify a consumer_group, session_timeout sets the maximum interval between heartbeats sent by a consumer group member to the broker. If a broker doesn’t receive a heartbeat from a group member before the timeout expires, it removes the member from the consumer group and initiates a rebalance. This field accepts Go duration format strings such as 100ms, 1s, or 5s.

Type: string

Default: 1m

start_offset

Specify the offset from which this input starts or restarts consuming messages. Restarts occur when the OffsetOutOfRange error is seen during a fetch.

Type: string

Default: earliest

Option Summary

committed

Prevents consuming a partition in a group if the partition has no prior commits. Corresponds to Kafka’s auto.offset.reset=none option

earliest

Start from the earliest offset. Corresponds to Kafka’s auto.offset.reset=earliest option.

latest

Start from the latest offset. Corresponds to Kafka’s auto.offset.reset=latest option.

timely_nacks_maximum_wait

EXPERIMENTAL: Specify a maximum period of time in which each message can be consumed and awaiting either acknowledgement or rejection before rejection is instead forced. This can be useful for avoiding situations where certain downstream components can result in blocked confirmation of delivery that exceeds SLAs. Accepts Go duration format strings such as 100ms, 1s, or 5s.

Type: string

topic_lag_refresh_period

The interval between consumer lag refreshes. During each cycle, this input asks the brokers for the consumer group’s committed offsets and the partition end offsets, and records the difference (the number of unread messages) for each topic partition in the consumer lag metric and the kafka_lag metadata field. Lag is only refreshed when consumer_group is set. This field accepts Go duration format strings such as 100ms, 1s, or 5s.

Type: string

Default: 5s

topics[]

A list of topics to consume from. You can list multiple comma-separated topics in a single element.

If you specify a consumer_group, partitions are automatically distributed across consumers of a topic. Otherwise, all partitions are consumed.

Alternatively, add a colon after the topic name to set the explicit partitions to consume. For example, foo:0 consumes the partition 0 of the topic foo. This syntax also supports ranges. For example, foo:0-10 consumes all partitions from 0 through to 10 inclusive.

Finally, add another colon after the partition to set an explicit offset to consume from. For example, foo:0:10 consumes the partition 0 of the topic foo starting from the offset 10. If the offset is not present (or remains unspecified) then the field start_offset determines which offset to start from.

Type: array<string>

# Examples:
topics:
  - foo
  - bar

# ---

topics:
  - things.*

# ---

topics:
  - "foo,bar"

# ---

topics:
  - "foo:0"
  - "bar:1"
  - "bar:3"

# ---

topics:
  - "foo:0,bar:1,bar:3"

# ---

topics:
  - "foo:0-5"

transaction_isolation_level

The isolation level for handling transactional messages. This setting determines how transactions are processed and affects data consistency guarantees.

Type: string

Default: read_uncommitted

Option Summary

read_committed

If set, only committed transactional records are processed.

read_uncommitted

If set, then uncommitted records are processed.