Tetrate Service ExpressVersion: Latest

Source

The differences between TSB and TSE API

Tetrate Service Express (TSE) utilizes many of the same components as the Tetrate Service Bridge(TSB) product but has the several distinctions. Go to Comparing TSE and TSB for more details.

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: tse
  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: tse
  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: tse
  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: tse
  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.

Source​

SourceScope​

IngressScopes​

IngressScope​

Scope​

RelationScopes​

RelationScope​

Scope​

ServiceRelation​

ServiceScopes​

ServiceScope​

Scope​

ScopeType​

ScopeType​

ScopeType​

SourceScopeType​

Source

SourceScope

IngressScopes

IngressScope

Scope

RelationScopes

RelationScope

Scope

ServiceRelation

ServiceScopes

ServiceScope

Scope

ScopeType

ScopeType

ScopeType

SourceScopeType