com.datatorrent.api.AutoMetric Maven / Gradle / Ivy
/**
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package com.datatorrent.api;
import java.io.IOException;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.util.Collection;
import java.util.Map;
/**
* A field which tracks an aspect of operator's progress is considered a metric. The value
* of the field is communicated from the execution environment to application master. The declared field
* name will be used as the metric key.
*
* @since 3.0.0
*/
@Documented
@Target({ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface AutoMetric
{
/**
* Represents collection of physical metrics.
*/
interface PhysicalMetricsContext
{
/**
* @return map of metric name to value
*/
Map getMetrics();
/**
* @return operator id
*/
int operatorId();
}
/**
* It aggregates metrics from multiple physical partitions of an operator to a logical one.
* An aggregator is provided as operator attribute. By default, when there isn't any aggregator set explicitly,
* the application master sums up all the number metrics.
*/
interface Aggregator
{
/**
* Aggregates values of a specific metric.
*
* @param windowId window id for which the values are aggregated.
* @param physicalMetrics collection of physical metrics from all the instances.
* @return map of aggregated metric keys and values.
*/
Map aggregate(long windowId, Collection physicalMetrics);
}
/**
* Provides information of dimension aggregations and time-buckets which are sent to Application data tracker.
* Application data tracker by default does certain aggregations for 1m, 1h,& 1d time buckets unless it overridden by
* the app developer by providing a dimension scheme as operator attribute.
*/
interface DimensionsScheme
{
/**
* Time buckets for eg. {1m, 1h}. Application data tracker by default does 1m, 1h & 1d aggregations but this
* will override it to just perform 1m and 1h aggregations.
*
* Time bucket format is a number followed by one of the below characters:
*
* - s - second
* - m - minute
* - h - hour
* - d - day
* - w - week
* - M - month
* - q - quarter
* - y - year
*
*
* @return time buckets.
*/
String[] getTimeBuckets();
/**
* Application data tracker by default performs SUM, MIN, MAX, AVG, COUNT, FIRST, LAST on all number metrics.
* An app developer can influence this behavior by creating a dimension scheme that has a mapping of logical metric name
* to aggregations. Stram will invoke this method for each logical metric and check if the aggregations are overwritten
* and will inform that to app data tracker.
*
* @param logicalMetricName logical metric name.
* @return aggregations eg. SUM, MIN, MAX, etc. that will be performed by app data tracker on a logical metric.
*/
String[] getDimensionAggregationsFor(String logicalMetricName);
}
/**
* Interface of transport for STRAM to push metrics data
*/
interface Transport
{
/**
* Pushes the metrics data (in JSON) to the transport.
*
* @param jsonData The metric data in JSON to be pushed to this transport
*/
void push(String jsonData) throws IOException;
/**
* Returns the number of milliseconds for resending the metric schema. The schema will need to be resent for
* unreliable transport. Return 0 if the schema does not need to be resent.
*/
long getSchemaResendInterval();
}
}