blob: cb26ce54c2d48a55f37ee1751c3511d41d3c1d88 [file] [log] [blame]
# 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
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# See the License for the specific language governing permissions and
# limitations under the License.
# Legacy metrics query protocol deprecated since 9.5.0. Replaced by the metrics-v3.
# Metrics v2 query protocol is an alternative metrics query(s) of original v1,
# defined in the metric.graphql, top-n-records.graphqls, and aggregation.graphqls.
# By leveraging the new ID rule(no register) in the v8, we could query metrics based on name(s) directly.
# Metrics type is a new concept since v8.
enum MetricsType {
# Can't find the metrics type definition.
# Regular value type is suitable for readMetricsValue, readMetricsValues and sortMetrics
# Metrics value includes multiple labels, is suitable for readLabeledMetricsValues
# Label should be assigned before the query happens, such as at the setting stage
# Heatmap value suitable for readHeatMap
# Top metrics is for readSampledRecords only.
input MetricsCondition {
# Metrics name, which should be defined in OAL script
# Such as:
# endpoint_resp_time = from(Endpoint.latency).avg()
# Then, `endpoint_resp_time`
name: String!
# Follow entity definition description.
entity: Entity!
input TopNCondition {
# Metrics name
name: String!
# Could be null if query the global top N.
parentService: String
# Normal service is the service having installed agent or metrics reported directly.
# Unnormal service is conjectural service, usually detected by the agent.
normal: Boolean
# Indicate the metrics entity scope.
# This is required in sortMetrics query.
# Only accept scope = Service/ServiceInstance/Endpoint, ignore others due to those are pointless.
scope: Scope
topN: Int!
order: Order!
# Define the metrics provided in the OAP server.
type MetricDefinition {
name: String!
type: MetricsType!
# Catalog includes
catalog: String
type MetricsValues {
# Could be null if no label assigned in the query condition
label: String
# Values of this label value.
values: IntValues
type HeatMap {
# Each element of values matches the time point of the query duration.
# The element in the IntValues represents the value of the same index bucket
values: [HeatMapColumn!]!
# Bucket describes the ranges of #values represent.
buckets: [Bucket!]!
type HeatMapColumn {
id: ID!
values: [Long!]!
# Bucket represents the value range.
type Bucket {
# Usually the number represents the min value of this bucket,
# could be `infinite-` string as unbounded value
min: String!
# Usually the number represents the max value of this bucket,
# could be `infinite+` string as unbounded value
max: String!
type SelectedRecord {
# Literal string name for visualization
name: String!
# ID represents the owner of this entity.
id: ID!
# Usually an integer value as this is metrics.
value: String
# Have value, Only if the record has related trace id.
# UI should show this as an attached value.
refId: ID
# Since 9.5.0, a value is Long type, and also nullable.
type NullableValue {
# This is the value, the caller must understand the Unit.
# Such as:
# 1. If ask for cpm metric, the unit and result should be count.
# 2. If ask for response time (p99 or avg), the unit should be millisecond.
value: Long!
# isEmptyValue indicates whether value == 0 represents actually zero(false, default) or no data(true).
isEmptyValue: Boolean!
extend type Query {
# Since 9.5.0 `typeOfMetrics` and `listMetrics` are moved to metrics-v3.
# Metrics definition metadata query. Response the metrics type which determines the suitable query methods.
# typeOfMetrics(name: String!): MetricsType!
# Get the list of all available metrics in the current OAP server.
# Param, regex, could be used to filter the metrics by name.
# listMetrics(regex: String): [MetricDefinition!]!
# Read metrics single value in the duration of required metrics
readMetricsValue(condition: MetricsCondition!, duration: Duration!): Long!
# Read metrics single value in the duration of required metrics
# NullableValue#isEmptyValue == true indicates no telemetry data rather than aggregated value is actually zero.
readNullableMetricsValue(condition: MetricsCondition!, duration: Duration!): NullableValue!
# Read time-series values in the duration of required metrics
readMetricsValues(condition: MetricsCondition!, duration: Duration!): MetricsValues!
# Read entity list of required metrics and parent entity type.
sortMetrics(condition: TopNCondition!, duration: Duration!): [SelectedRecord!]!
# Read value in the given time duration, usually as a linear.
# labels: the labels you need to query.
readLabeledMetricsValues(condition: MetricsCondition!, labels: [String!]!, duration: Duration!): [MetricsValues!]!
# Heatmap is bucket based value statistic result.
readHeatMap(condition: MetricsCondition!, duration: Duration!): HeatMap
# Deprecated since 9.3.0, replaced by readRecords defined in record.graphqls
# Read the sampled records
# TopNCondition#scope is not required.
readSampledRecords(condition: TopNCondition!, duration: Duration!): [SelectedRecord!]!