1 /** 2 * Interface to report and publish the collected SDK metric events to external 3 * sources. 4 * <p> 5 * Conceptually, a publisher receives a stream of {@link MetricCollection} 6 * objects overs its lifetime through its {@link #publish(MetricCollection)} )} 7 * method. Implementations are then free further aggregate these events into 8 * sets of metrics that are then published to some external system for further 9 * use. As long as a publisher is not closed, then it can receive {@code 10 * MetricCollection} objects at any time. In addition, as the SDK makes use of 11 * multithreading, it's possible that the publisher is shared concurrently by 12 * multiple threads, and necessitates that all implementations are threadsafe. 13 */ 14 @ThreadSafe 15 @SdkPublicApi 16 public interface MetricPublisher extends SdkAutoCloseable { 17 /** 18 * Notify the publisher of new metric data. After this call returns, the 19 * caller can safely discard the given {@code metricCollection} instance if 20 * it no longer needs it. Implementations are strongly encouraged to 21 * complete any further aggregation and publishing of metrics in an 22 * asynchronous manner to avoid blocking the calling thread. 23 * <p> 24 * With the exception of a {@code null} {@code metricCollection}, all 25 * invocations of this method must return normally. This is to ensure that 26 * callers of the publisher can safely assume that even in situations where 27 * an error happens during publishing that it will not interrupt the calling 28 * thread. 29 * 30 * @param metricCollection The collection of metrics. 31 * @throws IllegalArgumentException If {@code metricCollection} is {@code 32 * null}. 33 */ publish(MetricCollection metricCollection)34 void publish(MetricCollection metricCollection); 35 36 /** 37 * {@inheritDoc} 38 * <p> 39 * <b>Important:</b> Implementations must block the calling thread until all 40 * pending metrics are published and any resources acquired have been freed. 41 */ 42 @Override close()43 void close(); 44 } 45 46