org.apache.kafka.streams

Interface StreamsMetrics

public interface StreamsMetrics

The Kafka Streams metrics interface for adding metric sensors and collecting metric values.

Method Summary

Modifier and Type	Method and Description
Sensor	addLatencyAndThroughputSensor(String scopeName, String entityName, String operationName, Sensor.RecordingLevel recordingLevel, String... tags) Deprecated. since 2.5. Use addLatencyRateTotalSensor() instead.
Sensor	addLatencyRateTotalSensor(String scopeName, String entityName, String operationName, Sensor.RecordingLevel recordingLevel, String... tags) Add a latency, rate and total sensor for a specific operation, which will include the following metrics: average latency max latency invocation rate (num.operations / seconds) total invocation count Whenever a user records this sensor via Sensor.record(double) etc, it will be counted as one invocation of the operation, and hence the rate / count metrics will be updated accordingly; and the recorded latency value will be used to update the average / max latency as well.
Sensor	addRateTotalSensor(String scopeName, String entityName, String operationName, Sensor.RecordingLevel recordingLevel, String... tags) Add a rate and a total sensor for a specific operation, which will include the following metrics: invocation rate (num.operations / time unit) total invocation count Whenever a user records this sensor via Sensor.record(double) etc, it will be counted as one invocation of the operation, and hence the rate / count metrics will be updated accordingly.
Sensor	addSensor(String name, Sensor.RecordingLevel recordingLevel) Generic method to create a sensor.
Sensor	addSensor(String name, Sensor.RecordingLevel recordingLevel, Sensor... parents) Generic method to create a sensor with parent sensors.
Sensor	addThroughputSensor(String scopeName, String entityName, String operationName, Sensor.RecordingLevel recordingLevel, String... tags) Deprecated. since 2.5. Use addRateTotalSensor() instead.
Map<MetricName,? extends Metric>	metrics() Get read-only handle on global metrics registry.
void	recordLatency(Sensor sensor, long startNs, long endNs) Deprecated. since 2.5. Use Sensor#record() instead.
void	recordThroughput(Sensor sensor, long value) Deprecated. since 2.5. Use Sensor#record() instead.
void	removeSensor(Sensor sensor) Remove a sensor.

Method Detail

metrics

Map<MetricName,? extends Metric> metrics()

Get read-only handle on global metrics registry.

Returns:

Map of all metrics.

addLatencyRateTotalSensor

Sensor addLatencyRateTotalSensor(String scopeName,
                                 String entityName,
                                 String operationName,
                                 Sensor.RecordingLevel recordingLevel,
                                 String... tags)

Add a latency, rate and total sensor for a specific operation, which will include the following metrics:

1. average latency
2. max latency
3. invocation rate (num.operations / seconds)
4. total invocation count

Whenever a user records this sensor via Sensor.record(double) etc, it will be counted as one invocation of the operation, and hence the rate / count metrics will be updated accordingly; and the recorded latency value will be used to update the average / max latency as well. Note that you can add more metrics to this sensor after you created it, which can then be updated upon Sensor.record(double) calls. The added sensor and its metrics can be removed with removeSensor().

Parameters:

scopeName - name of the scope, which will be used as part of the metric type, e.g.: "stream-[scope]-metrics".

entityName - name of the entity, which will be used as part of the metric tags, e.g.: "[scope]-id" = "[entity]".

operationName - name of the operation, which will be used as the name of the metric, e.g.: "[operation]-latency-avg".

recordingLevel - the recording level (e.g., INFO or DEBUG) for this sensor.

tags - additional tags of the sensor

Returns:

The added sensor.

See Also:

addRateTotalSensor(String, String, String, Sensor.RecordingLevel, String...), removeSensor(Sensor), addSensor(String, Sensor.RecordingLevel, Sensor...)

addRateTotalSensor

Sensor addRateTotalSensor(String scopeName,
                          String entityName,
                          String operationName,
                          Sensor.RecordingLevel recordingLevel,
                          String... tags)

Add a rate and a total sensor for a specific operation, which will include the following metrics:

1. invocation rate (num.operations / time unit)
2. total invocation count

Whenever a user records this sensor via Sensor.record(double) etc, it will be counted as one invocation of the operation, and hence the rate / count metrics will be updated accordingly. Note that you can add more metrics to this sensor after you created it, which can then be updated upon Sensor.record(double) calls. The added sensor and its metrics can be removed with removeSensor().

Parameters:

scopeName - name of the scope, which will be used as part of the metrics type, e.g.: "stream-[scope]-metrics".

entityName - name of the entity, which will be used as part of the metric tags, e.g.: "[scope]-id" = "[entity]".

operationName - name of the operation, which will be used as the name of the metric, e.g.: "[operation]-total".

recordingLevel - the recording level (e.g., INFO or DEBUG) for this sensor.

tags - additional tags of the sensor

Returns:

The added sensor.

See Also:

addLatencyRateTotalSensor(String, String, String, Sensor.RecordingLevel, String...), removeSensor(Sensor), addSensor(String, Sensor.RecordingLevel, Sensor...)

addLatencyAndThroughputSensor

@Deprecated
Sensor addLatencyAndThroughputSensor(String scopeName,
                                                 String entityName,
                                                 String operationName,
                                                 Sensor.RecordingLevel recordingLevel,
                                                 String... tags)

Deprecated. since 2.5. Use addLatencyRateTotalSensor() instead.

Add a latency and throughput sensor for a specific operation, which will include the following sensors:

1. average latency
2. max latency
3. throughput (num.operations / time unit)

Also create a parent sensor with the same metrics that aggregates all entities with the same operation under the same scope if it has not been created.

Parameters:

scopeName - name of the scope, could be the type of the state store, etc.

entityName - name of the entity, could be the name of the state store instance, etc.

operationName - name of the operation, could be get / put / delete / etc.

recordingLevel - the recording level (e.g., INFO or DEBUG) for this sensor.

tags - additional tags of the sensor

Returns:

The added sensor.

recordLatency

@Deprecated
void recordLatency(Sensor sensor,
                               long startNs,
                               long endNs)

Deprecated. since 2.5. Use Sensor#record() instead.

Record the given latency value of the sensor. If the passed sensor includes throughput metrics, e.g., when created by the addLatencyAndThroughputSensor(String, String, String, Sensor.RecordingLevel, String...) method, then the throughput metrics will also be recorded from this event.

Parameters:

sensor - sensor whose latency we are recording.

startNs - start of measurement time in nanoseconds.

endNs - end of measurement time in nanoseconds.

addThroughputSensor

@Deprecated
Sensor addThroughputSensor(String scopeName,
                                       String entityName,
                                       String operationName,
                                       Sensor.RecordingLevel recordingLevel,
                                       String... tags)

Deprecated. since 2.5. Use addRateTotalSensor() instead.

Add a throughput sensor for a specific operation:

1. throughput (num.operations / time unit)

Also create a parent sensor with the same metrics that aggregates all entities with the same operation under the same scope if it has not been created. This sensor is a strict subset of the sensors created by addLatencyAndThroughputSensor(String, String, String, Sensor.RecordingLevel, String...).

Parameters:

scopeName - name of the scope, could be the type of the state store, etc.

entityName - name of the entity, could be the name of the state store instance, etc.

operationName - name of the operation, could be get / put / delete / etc.

recordingLevel - the recording level (e.g., INFO or DEBUG) for this sensor.

tags - additional tags of the sensor

Returns:

The added sensor.

recordThroughput

@Deprecated
void recordThroughput(Sensor sensor,
                                  long value)

Deprecated. since 2.5. Use Sensor#record() instead.

Record the throughput value of a sensor.

Parameters:

sensor - add Sensor whose throughput we are recording

value - throughput value

addSensor

Sensor addSensor(String name,
                 Sensor.RecordingLevel recordingLevel)

Generic method to create a sensor. Note that for most cases it is advisable to use addRateTotalSensor() or addLatencyRateTotalSensor() to ensure metric name well-formedness and conformity with the rest of the Kafka Streams code base. However, if the above two methods are not sufficient, this method can also be used.

Parameters:

name - name of the sensor.

recordingLevel - the recording level (e.g., INFO or DEBUG) for this sensor

Returns:

The added sensor.

See Also:

addRateTotalSensor(String, String, String, Sensor.RecordingLevel, String...), addLatencyRateTotalSensor(String, String, String, Sensor.RecordingLevel, String...), removeSensor(Sensor)

addSensor

Sensor addSensor(String name,
                 Sensor.RecordingLevel recordingLevel,
                 Sensor... parents)

Generic method to create a sensor with parent sensors. Note that for most cases it is advisable to use addRateTotalSensor() or addLatencyRateTotalSensor() to ensure metric name well-formedness and conformity with the rest of the Kafka Streams code base. However, if the above two methods are not sufficient, this method can also be used.

Parameters:

name - name of the sensor

recordingLevel - the recording level (e.g., INFO or DEBUG) for this sensor

Returns:

The added sensor.

See Also:

addRateTotalSensor(String, String, String, Sensor.RecordingLevel, String...), addLatencyRateTotalSensor(String, String, String, Sensor.RecordingLevel, String...), removeSensor(Sensor)

removeSensor

void removeSensor(Sensor sensor)

Remove a sensor.

Parameters:

sensor - sensor to be removed