MessageTimestampRouter

The following provides usage information for the Confluent SMT io.confluent.connect.transforms.MessageTimestampRouter.

Description

Update the record’s topic field as a function of the original topic value and the record’s timestamp field.

This is useful for sink connectors, because the topic field often determines the equivalent entity name in the destination system (for example, a database table or search index name). This SMT extracts the timestamp from the message’s specified field, which is especially useful for log data in which the timestamp is stored as a field in the message. See TimestampRouter to specify a basic topic pattern and timestamp format.

Installation

This transformation is developed by Confluent and does not ship by default with Apache Kafka® or Confluent Platform. You can install this transformation via the Confluent Hub Client:

confluent-hub install confluentinc/connect-transforms:latest

Example

The following example extracts a field named timestamp, time, or ts from the key, in the order specified by the message.timestamp.keys configuration. This timestamp value is originally in the format specified by message.timestamp.format. It adds a topic prefix and appends the timestamp of the format specified by topic.timestamp.format to the message topic.

"transforms": "MessageTimestampRouter",
"transforms.MessageTimestampRouter.type": "io.confluent.connect.transforms.MessageTimestampRouter",
"transforms.MessageTimestampRouter.topic.format": "foo-${topic}-${timestamp}",
"transforms.MessageTimestampRouter.message.timestamp.format": "yyyy-MM-dd",
"transforms.MessageTimestampRouter.topic.timestamp.format": "yyyy.MM.dd",
"transforms.MessageTimestampRouter.message.timestamp.keys": "timestamp,time,ts"

Message value: {"time":"2019-08-06"}

Topic (before): bar

Topic (after): foo-bar-2019.08.06

Properties

Name Description Type Default Valid Values Importance
topic.format Format string which can contain ${topic} and ${timestamp} as placeholders for the topic and timestamp, respectively. string ${topic}-${timestamp}   high
message.timestamp.format Format string for the message’s timestamp that is compatible with java.time.format.DateTimeFormatter. For additional details, see DateTimeFormatter. If no configuration or an empty string is provided, defaults to the format string for timestamp of ISO8601 standard, with mandatory date and optional time. string “”   low
topic.timestamp.format Format string for the topic’s timestamp that is compatible with java.time.format.DateTimeFormatter. For additional details, see DateTimeFormatter. string yyyy.MM.dd   high
message.timestamp.keys Comma-separated list of key names to look up the timestamp value in the message, in the order the names are listed. The timestamp is taken from the first found value. string     high

Predicates

Transformations can be configured with predicates so that the transformation is applied only to records which satisfy a condition. You can use predicates in a transformation chain and, when combined with the Apache Kafka® Filter, predicates can conditionally filter out specific records.

Predicates are specified in the connector configuration. The following properties are used:

  • predicates: A set of aliases for predicates applied to one or more transformations.
  • predicates.$alias.type: Fully qualified class name for the predicate.
  • predicates.$alias.$predicateSpecificConfig: Configuration properties for the predicate.

All transformations have the implicit config properties predicate and negate. A predicular predicate is associated with a transformation by setting the transformation’s predicate configuration to the predicate’s alias. The predicate’s value can be reversed using the negate configuration property.

Kafka Connect includes the following predicates:

  • org.apache.kafka.connect.predicates.TopicNameMatches: Matches records in a topic with a name matching a particular Java regular expression.
  • org.apache.kafka.connect.predicates.HasHeaderKey: Matches records which have a header with the given key.
  • org.apache.kafka.connect.predicates.RecordIsTombstone: Matches tombstone records (that is, records with a null value).

Predicate Examples

Example 1:

You have a source connector that produces records to many different topics and you want to do the following:

  • Filter out the records in the foo topic entirely.
  • Apply the ExtractField transformation with the field name other_field to records in all topics, except the topic bar.

To do this, you need to first filter out the records destined for the topic foo. The Filter transformation removes records from further processing.

Next, you use the TopicNameMatches predicate to apply the transformation only to records in topics which match a certain regular expression. The only configuration property for TopicNameMatches is a Java regular expression used as a pattern for matching against the topic name. The following example shows this configuration:

transforms=Filter
transforms.Filter.type=org.apache.kafka.connect.transforms.Filter
transforms.Filter.predicate=IsFoo

predicates=IsFoo
predicates.IsFoo.type=org.apache.kafka.connect.predicates.TopicNameMatches
predicates.IsFoo.pattern=foo

Using this configuration, ExtractField is then applied only when the topic name of the record is not bar. The reason you can’t use TopicNameMatches directly is because it would apply the transformation to matching topic names, not topic names which do not match. The transformation’s implicit negate configuration properties inverts the set of records which a predicate matches. This configuration addition is shown below:

transforms=Filter,Extract
transforms.Filter.type=org.apache.kafka.connect.transforms.Filter
transforms.Filter.predicate=IsFoo

transforms.Extract.type=org.apache.kafka.connect.transforms.ExtractField$Key
transforms.Extract.field=other_field
transforms.Extract.predicate=IsBar
transforms.Extract.negate=true

predicates=IsFoo,IsBar
predicates.IsFoo.type=org.apache.kafka.connect.predicates.TopicNameMatches
predicates.IsFoo.pattern=foo

predicates.IsBar.type=org.apache.kafka.connect.predicates.TopicNameMatches
predicates.IsBar.pattern=bar

Example 2:

The following configuration shows how to use a predicate in a transformation chain with the ExtractField transformation and the negate=true configuration property:

transforms=t2
transforms.t2.predicate=has-my-prefix
transforms.t2.negate=true
transforms.t2.type=org.apache.kafka.connect.transforms.ExtractField$Key
transforms.t2.field=c1
predicates=has-my-prefix
predicates.has-my-prefix.type=org.apache.kafka.connect.predicates.TopicNameMatch
predicates.has-my-prefix.pattern=my-prefix-.*

The transform t2 is only applied when the predicate has-my-prefix is false (using the negate=true parameter). The predicate is configured by the keys with prefix predicates.has-my-prefix. The predicate class is org.apache.kafka.connect.predicates.TopicNameMatch and it’s pattern parameter has the value my-prefix-.* . With this configuration, the transformation is applied only to records where the topic name does not start with my-prefix-.

Tip

The benefit of defining the predicate separately from the transform is it makes it easier to apply the same predicate to multiple transforms. For example, you can have one set of transforms use one predicate and another set of transforms use the same predicate for negation.

Predicate Properties

Name Description Type Default Valid Values Importance
TopicNameMatches A predicate which is true for records with a topic name that matches the configured regular expression. string   non-empty string, valid regex medium
HasHeaderKey A predicate which is true for records with at least one header with the configured name. string   non-empty string medium
RecordIsTombstone A predicate which is true for records which are tombstones (that is, records with a null value).       medium