OpenTelemetry SDK and instrumentations for Pharo
MIT License
OpenTelemetry SDK and instrumentations for Pharo. Use it to instrument, generate, collect, and export telemetry data (metrics, logs, and traces) to help you analyze your software’s performance and behavior.
Disclaimer: This is still in early development!
Metacello new
githubUser: 'Gabriel-Darbord' project: 'opentelemetry-pharo' commitish: 'main' path: 'src';
baseline: 'OpenTelemetry';
load
Warning: The current implementation uses MetaLink
s, so it is subject to all the problems that come with it, in particular:
The main instrumentation tools are in the OpenTelemetry-Instrumentation
package.
See the class comments for more details on each class.
Most of the API is class-side.
OTInstrumentationModule
and implement the class methods instrumentationName
, and instrumentations
that returns the list of instrumentations contained in that module.OTInstrumentation
and implement the following methods:
packageMatcher
, classMatcher
and methodMatcher
, which must return a kind of OTMatcher
to target the packages, classes and methods to be instrumented, respectively. When installing the instrumentation, the installer will go through the matching packages, then their matching classes, and finally install the instrumentation on the matching methods. See the OTMatcher
class-side API for some predefined matchers.configure:
to configure the installation of the metalink using the instance-side API of OTAgentInstaller
. Here you can specify which arguments are passed to the instrumentation methods.onMethodEnter:
to execute code before an instrumented method, with the configured arguments.onMethodExit:withValue:
to execute code after an instrumented method, with the configured arguments plus the method result.To handle the installation of instrumentation, the following classes (and their subclasses) respond to install
, uninstall
and reinstall
:
OTAgentInstaller
handles every instrumentation loaded into the image.OTInstrumentationModule
handles all of the instrumentations it groups.OTInstrumentation
handles itself.While an instrumentation can be implemented to do anything, it is usually used to generate traces.
To enable this, an OTInstrumenter
should be defined in the defineInstrumenter
method of your OTInstrumentation
subclass.
The simplest configuration is to just give it the instrumentation name, which should ideally match the instrumented library name in lower kebab-case, per OpenTelemetry standards:
defineInstrumenter
instrumenter := OTInstrumenter forInstrumentationNamed: 'instrumented-library-name'
Then, the instrumenter must be used to start a span:
onMethodEnter: arguments
"..."
span := instrumenter startRequest: myRequest.
"..."
The content of the request is used to extract a name and kind for the span, or to suppress it.
It can be anything, and how it is used for naming can also be configured by giving a block to OTInstrumenter>>#spanNameExtractor:
.
Finally, to end the span:
onMethodExit: arguments withValue: returnValue
"..."
instrumenter end.
"..."
See OTSpan
for the reification of trace data into OpenTelemetry.
Adding custom data to a span can be done using the attributeAt:put:
method.
The tools for exporting traces can be found in the OpenTelemetry-Exporters
package.
The exporter configuration is currently defined globally, it affects all instrumentations in the image.
Using an instrumenter will automatically send spans through the export process.
The configured exporter is a singleton in OTSpanExporter
.
The following exporters are available:
OTFileSpanExporter
exports to local JSON files, which by default go into the pharo-local/OpenTelemetry/traces/
folder of the image. This is the default exporter.OTZipkinSpanExporter
exports to a Zipkin platform. The HTTP client it uses can be accessed and configured through the httpClient
method.Currently, all sampling is head-based.
A sampler can be defined in the defineSampler
method of your OTInstrumentation
subclass.
See the OpenTelemetry-Sampling
package.
See an example instrumentation that generates traces for Shout.
Contributions are welcome! If you find any issues, have suggestions, or want to contribute new features, please create an issue or submit a pull request.