Tempo

  • By Canonical Observability
Channel Revision Published Runs on
latest/stable 30 24 Apr 2024
Ubuntu 22.04
latest/candidate 33 24 Apr 2024
Ubuntu 22.04
latest/beta 36 24 Apr 2024
Ubuntu 22.04
latest/edge 47 21 May 2024
Ubuntu 22.04
juju deploy tempo-k8s
Show information

Platform:

charms.tempo_k8s.v2.tracing

Overview.

This document explains how to integrate with the Tempo charm for the purpose of pushing traces to a tracing endpoint provided by Tempo. It also explains how alternative implementations of the Tempo charm may maintain the same interface and be backward compatible with all currently integrated charms.

Requirer Library Usage

Charms seeking to push traces to Tempo, must do so using the TracingEndpointRequirer object from this charm library. For the simplest use cases, using the TracingEndpointRequirer object only requires instantiating it, typically in the constructor of your charm. The TracingEndpointRequirer constructor requires the name of the relation over which a tracing endpoint is exposed by the Tempo charm, and a list of protocols it intends to send traces with. This relation must use the tracing interface. The TracingEndpointRequirer object may be instantiated as follows

from charms.tempo_k8s.v2.tracing import TracingEndpointRequirer

def __init__(self, *args):
    super().__init__(*args)
    # ...
    self.tracing = TracingEndpointRequirer(self,
        protocols=['otlp_grpc', 'otlp_http', 'jaeger_http_thrift']
    )
    # ...

Note that the first argument (self) to TracingEndpointRequirer is always a reference to the parent charm.

Alternatively to providing the list of requested protocols at init time, the charm can do it at any point in time by calling the TracingEndpointRequirer.request_protocols(*protocol:str, relation:Optional[Relation]) method. Using this method also allows you to use per-relation protocols.

Units of provider charms obtain the tempo endpoint to which they will push their traces by calling TracingEndpointRequirer.get_endpoint(protocol: str), where protocol is, for example:

  • otlp_grpc
  • otlp_http
  • zipkin
  • tempo

If the protocol is not in the list of protocols that the charm requested at endpoint set-up time, the library will raise an error.

Requirer Library Usage

The TracingEndpointProvider object may be used by charms to manage relations with their trace sources. For this purposes a Tempo-like charm needs to do two things

  1. Instantiate the TracingEndpointProvider object by providing it a reference to the parent (Tempo) charm and optionally the name of the relation that the Tempo charm uses to interact with its trace sources. This relation must conform to the tracing interface and it is strongly recommended that this relation be named tracing which is its default value.

For example a Tempo charm may instantiate the TracingEndpointProvider in its constructor as follows

from charms.tempo_k8s.v2.tracing import TracingEndpointProvider

def __init__(self, *args):
    super().__init__(*args)
    # ...
    self.tracing = TracingEndpointProvider(self)
    # ...

class TracingError

Description

Base class for custom errors raised by this library. None

class NotReadyError

Description

Raised by the provider wrapper if a requirer hasn't published the required data (yet). None

class ProtocolNotRequestedError

Description

Raised if the user attempts to obtain an endpoint for a protocol it did not request. None

class DataValidationError

Description

Raised when data validation fails on IPU relation data. None

class AmbiguousRelationUsageError

Description

Raised when one wrongly assumes that there can only be one relation on an endpoint. None

class Receiver

Description

Receiver data structure. None

class TracingProviderAppData

Description

Application databag model for the tracing provider. None

class TracingRequirerAppData

Description

Application databag model for the tracing requirer. None

class RelationNotFoundError

Description

Raised if no relation with the given name is found. None

Methods

RelationNotFoundError. __init__( self , relation_name: str )

class RelationInterfaceMismatchError

Description

Raised if the relation with the given name has an unexpected interface. None

Methods

RelationInterfaceMismatchError. __init__( self , relation_name: str , expected_relation_interface: str , actual_relation_interface: str )

class RelationRoleMismatchError

Description

Raised if the relation with the given name has a different role than expected. None

Methods

RelationRoleMismatchError. __init__( self , relation_name: str , expected_relation_role: RelationRole , actual_relation_role: RelationRole )

class RequestEvent

Description

Event emitted when a remote requests a tracing endpoint. None

Methods

RequestEvent. requested_receivers( self )

Description

List of receiver protocols that have been requested. None

class TracingEndpointProviderEvents

Description

TracingEndpointProvider events. None

class TracingEndpointProvider

Description

Class representing a trace receiver service. None

Methods

TracingEndpointProvider. __init__( self , charm: CharmBase , host: str , external_url , relation_name: str , internal_scheme )

Initialize.

Arguments

charm

a CharmBase instance that manages this instance of the Tempo service.

host

address of the node hosting the tempo server.

external_url

external address of the node hosting the tempo server, if an ingress is present.

relation_name

an optional string name of the relation between charm and the Tempo charmed service. The default is "tracing".

internal_scheme

scheme to use with internal urls.

TracingEndpointProvider. is_v2( self , relation: Relation )

Attempt to determine if this relation is a tracing v2 relation.

Description

Assumes that the V2 requirer will, as soon as possible (relation-created), publish the list of requested ingestion receivers (can be empty too).

TracingEndpointProvider. requested_protocols( self )

Description

All receiver protocols that have been requested by our related apps. None

TracingEndpointProvider. relations( self )

Description

All v2 relations active on this endpoint. None

TracingEndpointProvider. publish_receivers( self , receivers )

Description

Let all requirers know that these receivers are active and listening. None

class EndpointRemovedEvent

Description

Event representing a change in one of the receiver endpoints. None

class EndpointChangedEvent

Description

Event representing a change in one of the receiver endpoints. None

Methods

EndpointChangedEvent. receivers( self )

Description

Cast receivers back from dict. None

class TracingEndpointRequirerEvents

Description

TracingEndpointRequirer events. None

class TracingEndpointRequirer

Description

A tracing endpoint for Tempo. None

Methods

TracingEndpointRequirer. __init__( self , charm: CharmBase , relation_name: str , protocols )

Construct a tracing requirer for a Tempo charm.

Arguments

charm

a CharmBase object that manages this TracingEndpointRequirer object. Typically, this is self in the instantiating class.

relation_name

an optional string name of the relation between charm and the Tempo charmed service. The default is "tracing". It is strongly advised not to change the default, so that people deploying your charm will have a consistent experience with all other charms that provide tracing endpoints.

protocols

optional list of protocols that the charm intends to send traces with. The provider will enable receivers for these and only these protocols, so be sure to enable all protocols the charm or its workload are going to need.

Description

If your application supports pushing traces to a distributed tracing backend, the TracingEndpointRequirer object enables your charm to easily access endpoint information exchanged over a tracing relation interface.

TracingEndpointRequirer. request_protocols( self , protocols , relation )

Description

Publish the list of protocols which the provider should activate. None

TracingEndpointRequirer. relations( self )

Description

The tracing relations associated with this endpoint. None

TracingEndpointRequirer. is_ready( self , relation )

Description

Is this endpoint ready? None

TracingEndpointRequirer. get_all_endpoints( self , relation )

Description

Unmarshalled relation data. None

TracingEndpointRequirer. get_endpoint( self , protocol: ReceiverProtocol , relation )

Description

Receiver endpoint for the given protocol. None

TracingEndpointRequirer. otlp_grpc_endpoint( self )

Description

Use TracingEndpointRequirer.get_endpoint('otlp_grpc') instead. None

TracingEndpointRequirer. otlp_http_endpoint( self )

Description

Use TracingEndpointRequirer.get_endpoint('otlp_http') instead. None