Source

Source describes a set of observed resources that have a group of metrics that emit measurements at runtime. A source specifies what is being observed (which resource types: service, ingress hostnames, relation, …) and how it is being observed (with which scope of observation).

A telemetry source can observe different types of resources in a single or aggregated way depending on the defined scope. A scope can be of type ServiceScope, IngressScope, or RelationScope, and they define the wingspan of the telemetry source in the mesh. Each scope contains information to determine if it is a single standalone source or an aggregation of standalone sources of the same type.

ServiceScope can be one of the following types which define the span of a service’s telemetry source in the mesh as:

  • INSTANCE: A single specific service instance (pod or VM) in a cluster.
  • SERVICE: An aggregation of all instances of a specific service of a concrete version (subset) in a cluster.
  • SUBSET: An aggregation of all instances of a specific service of a concrete version (subset) across clusters.
  • GLOBAL: An aggregation of all instances from all the versions of a specific service across clusters.

IngressScope can be one the following types which define the span of Ingress hostname’s telemetry source in the mesh as:

  • HOSTNAME: A ingress’s hostname in a concrete cluster.
  • GLOBAL: A ingress’s hostname across clusters.

A Telemetry source can also observe relation between resources. A relation is the physical connection between resources when a call between them has been done. For instance, a relation exists when a gateway calls a service or vice versa, or a service calls another service. That relation (call) can be seen (detected) from the server side, client-side, or both. For instance, when a gateway calls a service, and both resources are observed, the relation can be seen from both sides, the client and the server. In this case, the gateway is the client-side of the relation observation and the service is the server side of the observation. Each of the observation points (client or server) in the relation will produce different measurements for the same metric. Which means that, if we take the duration metric of the relation, we will have a concrete value (measurement) from the client point of view and another value from the server point view, where the client-side observed duration will be greater than the server side duration, in which the difference between durations is the network/transport introduced latency.

RelationScope can be one the following types which define the span of a relation telemetry source in the mesh as:

  • SERVICE: A relation between logical services.

To understand a bit better what and how a telemetry source can observe, let’s assume we have deployed the classic Istio bookinfo demo application in 2 clusters, demo and demo-disaster-recovery. If we take as an example the reviews service which has 3 different versions (subsets V1, V2, and V3) for what is being observed, we will have different telemetry sources available which will tell us how (which scope) they are being observed.

An INSTANCE scoped telemetry source for a concrete review service instance (pod) running on the demo cluster will be:

apiVersion: observability.telemetry.tsb.tetrate.io/v2
kind: Source
metadata:
  organization: myorg
  service: reviews.bookinfo
  name: reviews-v1-545db77b95-vhtlj
spec:
  belongsTo: organizations/myorg/services/reviews.bookinfo
  metric_source_key: djF8cmV2aWV3c3xib29raW5mb3xkZW1vfC0=.1_cmV2aWV3cy12MS01NDVkYjc3Yjk1LXZodGxq
  service_scopes:
    - type: INSTANCE
      scope:
        instance: reviews-v1-545db77b95-vhtlj
        subset: v1
        service: reviews
        namespace: bookinfo
        cluster: demo
      deployment: organizations/myorg/clusters/demo/namespaces/bookinfo/services/reviews

A SUBSET scoped telemetry source for the reviews service of v1 subset running on the demo cluster will be:

apiVersion: observability.telemetry.tsb.tetrate.io/v2
kind: Source
metadata:
  organization: myorg
  service: reviews.bookinfo
  name: reviews-v1-demo
spec:
  belongsTo: organizations/myorg/services/reviews.bookinfo
  metric_source_key: djF8cmV2aWV3c3xib29raW5mb3xkZW1vfC0=.1
  service_scopes:
    - type: SUBSET
      scope:
        subset: v1
        service: reviews
        namespace: bookinfo
        cluster: demo
      deployment: organizations/myorg/clusters/demo/namespaces/bookinfo/services/reviews

A GLOBAL_SUBSET scope telemetry source for the reviews services of version v1 running across clusters will be:

apiVersion: observability.telemetry.tsb.tetrate.io/v2
kind: Source
metadata:
  organization: myorg
  service: reviews.bookinfo
  name: reviews-v1
spec:
  belongsTo: organizations/myorg/services/reviews.bookinfo
  metric_source_key: djF8cmV2aWV3c3xib29raW5mb3wqfCo=.1
  service_scopes:
    - type: GLOBAL_SUBSET
      scope:
        subset: v1
        service: reviews
        namespace: bookinfo
      deployment: organizations/myorg/clusters/demo/namespaces/bookinfo/services/reviews

A GLOBAL scoped telemetry source for the reviews service of all subsets(v1, v2, and v3) running across all clusters will be:

apiVersion: observability.telemetry.tsb.tetrate.io/v2
kind: Source
metadata:
  organization: myorg
  service: reviews.bookinfo
  name: reviews
spec:
  belongsTo: organizations/myorg/services/reviews.bookinfo
  metric_source_key: djF8cmV2aWV3c3xib29raW5mb3wqfCo=.1
  service_scopes:
    - type: GLOBAL
      scope:
        service: reviews
        namespace: bookinfo
      deployment: organizations/myorg/clusters/demo/namespaces/bookinfo/services/reviews

Source

Source identifies a set of observed resources that have a group of metrics that emit measurements at runtime.

Field Description Validation Rule

belongsTo

string
OUTPUT_ONLY
Which concrete TSB resource in the configuration hierarchy this telemetry source belongs to. For instance, a telemetry source can belong to a service,or a gateway, or a workspace, or any other resource in the configuration hierarchy.

metricSourceKey

string
OUTPUT_ONLY
A key to query metric measurements from the resources that the telemetry source is observing.

type

tetrateio.api.tsb.observability.telemetry.v2.SourceScopeType
The type of resource which the telemetry source is observing, a service, an ingress, or a relation.

scope

tetrateio.api.tsb.observability.telemetry.v2.SourceScope

SourceScope

Source scope defines the source’s wingspan in the mesh. It defines how we are observing the resources. For instance we can observer a resources at service, ingress, or relation level.

Field Description Validation Rule

serviceScopes

tetrateio.api.tsb.observability.telemetry.v2.SourceScope.ServiceScopes oneof scope
ServiceScopes defines one or many service’s telemetry source wingspan in the mesh.

ingressScopes

tetrateio.api.tsb.observability.telemetry.v2.SourceScope.IngressScopes oneof scope
IngressScopes defines one or many Ingress’s telemetry source wingspan in the mesh.

relationScopes

tetrateio.api.tsb.observability.telemetry.v2.SourceScope.RelationScopes oneof scope
RelationScopes defines one or many Relation’s telemetry source wingspan in the mesh.

IngressScopes

IngressScopes defines one or many Ingress’s hostname telemetry source wingspan in the mesh.

Field Description Validation Rule

scopes

List of tetrateio.api.tsb.observability.telemetry.v2.SourceScope.IngressScopes.IngressScope
Multiple IngressScope can be defined to group under a single telemetry source different ingresses.

IngressScope

An ingress defines the telemetry source wingspan in the mesh of ingress’s hostname.

Field Description Validation Rule

type

tetrateio.api.tsb.observability.telemetry.v2.SourceScope.IngressScopes.IngressScope.ScopeType
Type of the scope.

scope

tetrateio.api.tsb.observability.telemetry.v2.SourceScope.IngressScopes.IngressScope.Scope
The scope that this telemetry source spans over.

deployment

string
The FQN of the service deployment in a concrete cluster related with this telemetry source scope. Will have a value for scope types HOSTNAME.

Scope

Each of the scope properties can have the following values:

  • A non empty value.
  • An empty value or absence of the property act as a wildcard, meaning any possible value.
Field Description Validation Rule

hostname

string
hostname is always a concrete value

ingressService

string
ingress_service is always a concrete value

cluster

string
cluster can be a concrete value or an empty value meaning any cluster.

RelationScopes

RelationScopes represents the physical connection that exists between observable resources. A relation can represent for instance the physical connection that exist when a call between services is done:

  • Between a gateway and a service or vice versa.
  • Between a service and another service. This observation can produce client-side measurements, server side measurements or both.
Field Description Validation Rule

scopes

List of tetrateio.api.tsb.observability.telemetry.v2.SourceScope.RelationScopes.RelationScope
Multiple RelationScope can be defined to group under a single telemetry source different relations.

RelationScope

Field Description Validation Rule

type

tetrateio.api.tsb.observability.telemetry.v2.SourceScope.RelationScopes.RelationScope.ScopeType
Type of the scope.

scope

tetrateio.api.tsb.observability.telemetry.v2.SourceScope.RelationScopes.RelationScope.Scope
The scope that this telemetry source spans over.

Scope
Field Description Validation Rule

serviceRelation

tetrateio.api.tsb.observability.telemetry.v2.SourceScope.RelationScopes.RelationScope.ServiceRelation oneof relation_type

ServiceRelation

A relation between logical services.

Field Description Validation Rule

source

string
The source resource’s fqn of the relation between two logical services.

target

string
The target resource’s fqn of the relation between two logical services.

ServiceScopes

ServiceScopes defines one or many service’s telemetry source wingspan in the mesh.

Field Description Validation Rule

scopes

List of tetrateio.api.tsb.observability.telemetry.v2.SourceScope.ServiceScopes.ServiceScope
Multiple ServiceScope can be defined to group under a single telemetry source different services.

ServiceScope

A service scope defines the telemetry source wingspan in the mesh of a service.

Field Description Validation Rule

type

tetrateio.api.tsb.observability.telemetry.v2.SourceScope.ServiceScopes.ServiceScope.ScopeType
Type of the scope.

scope

tetrateio.api.tsb.observability.telemetry.v2.SourceScope.ServiceScopes.ServiceScope.Scope
The scope that this telemetry source spans over.

deployment

string
The FQN of the service deployment in a concrete cluster related with this telemetry source scope. Will have a value for scope types INSTANCE or SERVICE.

Scope

Each of the scope properties can have the following values:

  • A non empty value.
  • An empty value or absence of the property act as a wildcard, meaning any possible value.
Field Description Validation Rule

instance

string
instance is a concrete value or an empty value meaning any instance.

subset

string
subset can be a concrete value or an empty value meaning any subset.

service

string
service is always a concrete value.

namespace

string
namespace is always a concrete value.

cluster

string
cluster can be a concrete value or an empty value meaning any cluster.

ScopeType

ScopeType denotes the wingspan of a telemetry source for an ingress’s hostname.

Field Number Description

INVALID

0

HOSTNAME

1

A hostname telemetry source that belongs to a specific ingress instance in a cluster.

GLOBAL

2

A global telemetry source of a hostname from an ingress across clusters.

ScopeType

ScopeType denotes the wingspan of a telemetry source for relation between resources.

Field Number Description

INVALID

0

SERVICE

1

A service telemetry source that belongs to a specific relation between logical services.

ScopeType

ScopeType denotes the wingspan of a telemetry source for a service.

Field Number Description

INVALID

0

INSTANCE

1

A instance telemetry source belongs to a specific service instance (pod or VM) in a cluster.

SERVICE

2

A service telemetry source belongs to a specific service, without subsets, in a cluster.

SUBSET

3

A subset telemetry source belongs to a specific service of a concrete subset in a cluster.

GLOBAL_SUBSET

4

A global subset telemetry source represents a concrete subset from a service across cluster. Subset scope type does not apply to ingress services.

GLOBAL

5

A global telemetry source represents all subsets from a service across clusters.

SourceScopeType

The type of scopes which defines telemetry source’s wingspan in the mesh.

Field Number Description

INVALID

0

SERVICE

1

A telemetry source service based scope.

INGRESS

2

A telemetry source ingress's hostname based scope.

RELATION

3

A telemetry source relation based scope.