From 1889f366b91b3563348ef0b69aa0ce2e8da553da Mon Sep 17 00:00:00 2001 From: Kieran Gorman Date: Thu, 2 May 2019 18:35:11 +0100 Subject: [PATCH] async_producer: clarify ProducerMessage `Timestamp` doc The `Timestamp` field was introduced in https://github.com/Shopify/sarama/pull/678 and at this point was only set by the broker. Subsequent to this, the changes described in [KIP-32] were implemented, allowing the `Timestamp` of the message to be set by a producer when the broker was configured to use `CreateTime`. This commit updates the doc on the ProducerMessage struct to reflect that depending on which of the `CreateTime` and `LogAppendTime` modes are active, the `Timestamp` can be meaningfully set by either the request or the response. [KIP-32]: https://cwiki.apache.org/confluence/display/KAFKA/KIP-32+-+Add+timestamps+to+Kafka+message --- async_producer.go | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/async_producer.go b/async_producer.go index 5db0a73d4..11e084961 100644 --- a/async_producer.go +++ b/async_producer.go @@ -191,10 +191,17 @@ type ProducerMessage struct { // Partition is the partition that the message was sent to. This is only // guaranteed to be defined if the message was successfully delivered. Partition int32 - // Timestamp is the timestamp assigned to the message by the broker. This - // is only guaranteed to be defined if the message was successfully - // delivered, RequiredAcks is not NoResponse, and the Kafka broker is at - // least version 0.10.0. + // Timestamp can vary in behaviour depending on broker configuration, being + // in either one of the CreateTime or LogAppendTime modes (default CreateTime), + // and requiring version at least 0.10.0. + // + // When configured to CreateTime, the timestamp is specified by the producer + // either by explicitly setting this field, or when the message is added + // to a produce set. + // + // When configured to LogAppendTime, the timestamp assigned to the message + // by the broker. This is only guaranteed to be defined if the message was + // successfully delivered and RequiredAcks is not NoResponse. Timestamp time.Time retries int