The Istio Telemetry API (telemetry.istio.io) provides configuration resources for managing observability within an Istio service mesh. The Telemetry resource enables flexible configuration of metrics, access logs, and distributed tracing for workloads. It uses the concept of providers to indicate the protocol or integration type, and supports fine-grained control over what telemetry data is collected and where it is sent.
openapi: 3.1.0
info:
title: Istio Telemetry API
description: >-
The Istio Telemetry API (telemetry.istio.io) provides configuration
resources for managing observability within an Istio service mesh. The
Telemetry resource enables flexible configuration of metrics, access logs,
and distributed tracing for workloads. It uses the concept of providers to
indicate the protocol or integration type, and supports fine-grained control
over what telemetry data is collected and where it is sent. These resources
are defined as Kubernetes Custom Resource Definitions (CRDs) and are
accessed via the Kubernetes API server.
version: v1
contact:
name: Istio
url: https://istio.io/
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
externalDocs:
description: Istio Telemetry Configuration Reference
url: https://istio.io/latest/docs/reference/config/telemetry/
servers:
- url: https://{cluster}/apis/telemetry.istio.io/v1
description: Kubernetes API server endpoint for Istio Telemetry v1
variables:
cluster:
default: kubernetes.default.svc
description: Kubernetes API server hostname
paths:
/namespaces/{namespace}/telemetries:
get:
operationId: listTelemetries
summary: Istio List Telemetry resources
description: >-
List all Telemetry resources in the specified namespace. A Telemetry
resource configures the behavior of the Istio telemetry system,
including metrics collection, access logging, and distributed tracing.
tags:
- Telemetry
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/labelSelector'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/continue'
responses:
'200':
description: Successful response containing list of Telemetry resources
content:
application/json:
schema:
$ref: '#/components/schemas/TelemetryList'
'401':
description: Unauthorized
post:
operationId: createTelemetry
summary: Istio Create a Telemetry resource
description: Create a new Telemetry resource in the specified namespace.
tags:
- Telemetry
parameters:
- $ref: '#/components/parameters/namespace'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Telemetry'
responses:
'201':
description: Telemetry resource created
content:
application/json:
schema:
$ref: '#/components/schemas/Telemetry'
'401':
description: Unauthorized
'409':
description: Conflict - resource already exists
/namespaces/{namespace}/telemetries/{name}:
get:
operationId: getTelemetry
summary: Istio Get a Telemetry resource
description: Read the specified Telemetry resource.
tags:
- Telemetry
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Telemetry'
'401':
description: Unauthorized
'404':
description: Not found
put:
operationId: replaceTelemetry
summary: Istio Replace a Telemetry resource
description: Replace the specified Telemetry resource.
tags:
- Telemetry
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Telemetry'
responses:
'200':
description: Telemetry resource replaced
content:
application/json:
schema:
$ref: '#/components/schemas/Telemetry'
'401':
description: Unauthorized
'404':
description: Not found
delete:
operationId: deleteTelemetry
summary: Istio Delete a Telemetry resource
description: Delete the specified Telemetry resource.
tags:
- Telemetry
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
responses:
'200':
description: Telemetry resource deleted
'401':
description: Unauthorized
'404':
description: Not found
components:
parameters:
namespace:
name: namespace
in: path
required: true
description: The Kubernetes namespace
schema:
type: string
name:
name: name
in: path
required: true
description: The resource name
schema:
type: string
labelSelector:
name: labelSelector
in: query
description: A selector to restrict the list of returned objects by their labels
schema:
type: string
limit:
name: limit
in: query
description: Maximum number of resources to return
schema:
type: integer
continue:
name: continue
in: query
description: Continue token for paginated list requests
schema:
type: string
schemas:
ObjectMeta:
type: object
properties:
name:
type: string
description: Name of the resource
namespace:
type: string
description: Namespace of the resource
labels:
type: object
additionalProperties:
type: string
annotations:
type: object
additionalProperties:
type: string
creationTimestamp:
type: string
format: date-time
resourceVersion:
type: string
ListMeta:
type: object
properties:
resourceVersion:
type: string
continue:
type: string
Telemetry:
type: object
properties:
apiVersion:
type: string
enum:
- telemetry.istio.io/v1
kind:
type: string
enum:
- Telemetry
metadata:
$ref: '#/components/schemas/ObjectMeta'
spec:
type: object
properties:
selector:
type: object
properties:
matchLabels:
type: object
additionalProperties:
type: string
description: Workload selector to apply the telemetry configuration.
tracing:
type: array
items:
type: object
properties:
providers:
type: array
items:
type: object
properties:
name:
type: string
description: Name of the tracing provider configured in MeshConfig.
description: Tracing providers to use.
randomSamplingPercentage:
type: number
description: >-
Controls the rate at which traffic will be selected for
tracing (0.0 to 100.0).
disableSpanReporting:
type: boolean
description: Disables span reporting.
customTags:
type: object
additionalProperties:
type: object
properties:
literal:
type: object
properties:
value:
type: string
environment:
type: object
properties:
name:
type: string
defaultValue:
type: string
header:
type: object
properties:
name:
type: string
defaultValue:
type: string
description: Custom tags to add to spans.
description: Tracing configuration.
metrics:
type: array
items:
type: object
properties:
providers:
type: array
items:
type: object
properties:
name:
type: string
description: Name of the metrics provider configured in MeshConfig.
description: Metrics providers to use.
overrides:
type: array
items:
type: object
properties:
match:
type: object
properties:
metric:
type: string
enum:
- ALL_METRICS
- REQUEST_COUNT
- REQUEST_DURATION
- REQUEST_SIZE
- RESPONSE_SIZE
- TCP_OPENED_CONNECTIONS
- TCP_CLOSED_CONNECTIONS
- TCP_SENT_BYTES
- TCP_RECEIVED_BYTES
- GRPC_REQUEST_MESSAGES
- GRPC_RESPONSE_MESSAGES
description: Metric to match.
mode:
type: string
enum:
- CLIENT_AND_SERVER
- CLIENT
- SERVER
description: Controls which mode of metrics generation is selected.
disabled:
type: boolean
description: Disable the matched metric.
tagOverrides:
type: object
additionalProperties:
type: object
properties:
operation:
type: string
enum:
- UPSERT
- REMOVE
value:
type: string
description: Tag overrides for the matched metric.
description: Metric override directives.
description: Metrics configuration.
accessLogging:
type: array
items:
type: object
properties:
providers:
type: array
items:
type: object
properties:
name:
type: string
description: Name of the access logging provider configured in MeshConfig.
description: Access logging providers to use.
disabled:
type: boolean
description: Disable all access logging for matched workloads.
filter:
type: object
properties:
expression:
type: string
description: >-
CEL expression to filter access log entries (e.g.
response.code >= 400).
description: Filter for access log entries.
description: Access logging configuration.
targetRefs:
type: array
items:
type: object
properties:
kind:
type: string
group:
type: string
name:
type: string
description: References to the target resources.
TelemetryList:
type: object
properties:
apiVersion:
type: string
kind:
type: string
enum:
- TelemetryList
metadata:
$ref: '#/components/schemas/ListMeta'
items:
type: array
items:
$ref: '#/components/schemas/Telemetry'
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: Kubernetes API server bearer token authentication
tags:
- name: Telemetry
description: Telemetry configuration for metrics, tracing, and access logging
externalDocs:
url: https://istio.io/latest/docs/reference/config/telemetry/