diff --git hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-timelineservice/src/main/java/org/apache/hadoop/yarn/server/timelineservice/storage/TimelineReader.java hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-timelineservice/src/main/java/org/apache/hadoop/yarn/server/timelineservice/storage/TimelineReader.java new file mode 100644 index 0000000..b1fb9e4 --- /dev/null +++ hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-timelineservice/src/main/java/org/apache/hadoop/yarn/server/timelineservice/storage/TimelineReader.java @@ -0,0 +1,174 @@ +/** + * 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 org.apache.hadoop.yarn.server.timelineservice.storage; + +import org.apache.hadoop.classification.InterfaceAudience; +import org.apache.hadoop.classification.InterfaceStability; +import org.apache.hadoop.yarn.api.records.timelineservice.TimelineEntity; + +import java.io.IOException; +import java.util.EnumSet; +import java.util.Set; + +/** + * This interface is for fetching timeline data from storage + */ +@InterfaceAudience.Private +@InterfaceStability.Unstable +public interface TimelineReader { + + /** + *
The API to fetch the single entity given the entity identifier in the + * scope of the given context.
+ * + * @param userId + * context user Id (mandatory) + * @param clusterId + * context cluster Id (mandatory) + * @param flowId + * context flow Id (optional) + * @param flowRunId + * context flow run Id (optional) + * @param appId + * context app Id (mandatory) + * @param entityType + * entity type (mandatory) + * @param entityId + * entity Id (mandatory) + * @param fieldsToRetrieve + * the fields to be be returned (optional, by default {@link Field#ALL} + * will be retrieved) + * @return a {@link TimelineEntity} instance or null. The entity will only + * contain the metadata plus the given fields to retrieve + * @throws IOException + */ + TimelineEntity getEntity(String userId, String clusterId, String flowId, + String flowRunId, String appId, String entityType, String entityId, + EnumSetThe API to search for a set of entities of the given the entity type in + * the scope of the given context which matches the given predicates. The + * predicates include the created/modified time window, the number of entities + * to return at most, and the entities can be filtered by checking whether + * they contain the given info/configs entries in the form of key/value pairs, + * and the given events/metrics in the form of the Ids, and whether they + * relate to/are related to other entities
+ * + * @param userId + * context user Id (mandatory) + * @param clusterId + * context cluster Id (mandatory) + * @param flowId + * context flow Id (optional) + * @param flowRunId + * context flow run Id (optional) + * @param appId + * context app Id (mandatory) + * @param entityType + * the type of entities to fetch (mandatory) + * @param limit + * the number of entities to fetch at most (optional, by default the limit + * is 1000) + * @param createdTimeBegin + * the matched entities must be created no early than this time + * (optional, by default the value is 0) + * @param createdTimeEnd + * the matched entities must be created no later than this time + * (optional, by default the value is {@link Long#MAX_VALUE}) + * @param modifiedTimeBegin + * the matched entities must be modified no early than this time + * (optional, by default the value is 0) + * @param modifiedTimeEnd + * the matched entities must be modified no later than this time + * (optional, by default the value is {@link Long#MAX_VALUE}) + * @param relatesTo + * the matched entities must relate to the given entities (optional) + * @param isRelatedTo + * the matched entities must be related to the given entities (optional) + * @param info + * the matched entities must contain the given info represented by + * key/value pairs (optional) + * @param configs + * the matched entities must contain the given configs represented by + * key/value pairs (optional) + * @param events + * the matched entities must contain the given events identified by Id + * (optional) + * @param metrics + * the matched entities must contain the given metrics identified by Id + * (optional) + * @param fieldsToRetrieve + * the fields to be be returned (optional, by default {@link Field#ALL} + * will be retrieved) + * @return a set of {@link TimelineEntity} instances of the given entity type + * in the given context scope which matches the given predicates + * ordered by created time. Each entity will only contain the metadata + * plus the given fields to retrieve + * @throws IOException + */ + // TODO: We may want to support more sophisticated predicates for metrics such + // as comparing against the aggregation value. + // TODO: We may need to retrieve partial configs and metrics + // TODO: We may want to support different sorting criteria + Set