Famix-OpenTelemetry

Famix metamodel for OpenTelemetry traces.

Installation

Metacello new
  githubUser: 'moosetechnology' project: 'Famix-OpenTelemetry' commitish: 'main' path: 'src';
  baseline: 'FamixOpenTelemetry';
  load

Importing

OpenTelemetry traces can be stored in a variety of telemetry backends, such as Zipkin or any OTelCollector. To support this modularity, the importer works like an ELT pipeline.

• Extractors retrieve the raw trace data from a source outside the image and deserialize it. Some extractors can output the retrieved data to a file, by configuring them with outputFilename:. The data can then be extracted from the file, for example with OTelJSONFileExtractor.
• Loaders understand a specific raw data structure and use it to build the model.
• Transformers are optional, they can process or apply modifications to the trace model.

importer := OpenTelemetryImporter new.
importer
  extractor: (OTelZipkinExtractor new endpoint: 'http://localhost:9411');
  loader: OTelZipkinLoader new;
  transformers: { OTelTagTransformer new
      predicate: [ :tag | "match a tag" ];
      block: [ :value | "compute its new value" ] }.
importer import. "returns a filled FamixOTelModel"

Supported Telemetry Aggregators

Aggregator	Baseline
Zipkin	default
Elasticsearch	elasticsearch

Available Transformers

Transformer	Description	Baseline
TagTransformer	modifies Span tags that match a predicate with a pluggable block	default
FamixLinker	links Spans to their origin in a Famix model	default
FamixValueLinker	links origin and generates a FamixValue model from serialized arguments and result	value

Examples

Example with ElasticSearch

Metacello new
  githubUser: 'moosetechnology' project: 'Famix-OpenTelemetry' commitish: 'main' path: 'src';
  baseline: 'FamixOpenTelemetry';
  load: 'elasticsearch'.

elasticExtractor := OTelElasticsearchExtractor new.
elasticExtractor
  beHttps;
  endpoint: 'endpointToElastic';
  index: '<your index name>';
  apiKey: '<your api key>';
  size: 30.

importer := OpenTelemetryImporter new.
importer
  extractor: elasticExtractor;
  loader: OTelElasticsearchOtelLoader new.
model := importer import. "returns a filled FamixOTelModel"

model allWithType: FamixOTelTrace.

Modeling Values

It is possible to model serialized runtime values stored in traces using Famix-Value. To enable this feature, load the value group:

Metacello new
  githubUser: 'moosetechnology' project: 'Famix-OpenTelemetry' commitish: 'main' path: 'src';
  baseline: 'FamixOpenTelemetry';
  load: 'value'

A transformer, such as an instance of OTelFamixValueLinker, can be added to the import pipeline to create a FamixValue model.
The values can also be linked to the model of the application that produced them by configuring the given FamixValue importer.
In order to enable navigation between the traces and the values when inspecting entities, they must coexist in the same FamixOTelValueModel.

traceModel := FamixOTelValueModel new.
javaModel := MooseModel root at: 1. "model of the Java application that produced the traces"
importer loader: (OTelZipkinLoader new model: traceModel).
importer transformers: { OTelFamixValueLinker new
    "keys of tags containing the relevant values"
    classKey: 'class';
    methodKey: 'method';
    argsKey: 'arguments';
    resultKey: 'result';
    "configure a FamixValue importer, this one understands JSON from the Jackson Java library"
    importer: (FamixValueJavaJacksonImporter new
        model: traceModel;
        "configure an entity finder, this one is for searching a FamixJava model"
        entityFinder: (FamixJavaEntityFinder new model: javaModel)) }.
importer import. "fills traceModel with FamixOTel and FamixValue entities"