Provides configurable instrumentation modules for the OpenTelemetry Agent to instrument a Frank Framework instance.
The OpenTelemetry Agent instruments a lot of libraries and frameworks by default, this project aims to provide a production grade 'plug & play' module which helps to gain additional insights on the path a message took within a Frank application.
This project is still under heavy development and the master is based on the 7.8.3 release of the Frank Framework. The highest priority is to provide correct traces at first, then look into supporting features of newer versions of the framework.
Other supported version (see branches):
- 7.7.X releases
If you have any feedback, ideas or found any issues, please let us know by creating an issue.
- Start Zipkin with the following command
docker run -d -p 9411:9411 openzipkin/zipkin, open http://localhost:9411/zipkin/ to access the UI. - Download the OpenTelemetry Agent to a common folder.
- Build Frank OTEL Instrumentation module and place .jar in a common folder.
- Add the following JVM arguments:
-javaagent:path/to/common-folder/opentelemetry-javaagent.jar -Dotel.traces.exporter=zipkin -Dotel.resource.attributes=service.name=Frank -Dotel.javaagent.extensions=path/to/common-folder/frank-otel-instrumentation-1.0-SNAPSHOT.jar - Start JVM, trigger some Adapters and check Zipkin!
The Frank OTEL Instrumentation modules provide the following configurable options:
If true, whenever an exit is taken, a tag will be added to the current span.
- frank.instrumentation.exits=
true|false - default:
true
To disable this feature, add the following JVM property:
- -Dfrank.instrumentation.exits=false
If true, whenever a forward is taken, a tag will be added to the current span.
- frank.instrumentation.forwards=
true|false - default:
true
To disable this feature, add the following JVM property:
- -Dfrank.instrumentation.forwards=false
If true, whenever a pipeline is finished, a tag for each entry in the log context will be added to the current span.
- frank.instrumentation.logContext=
true|false - default:
true
To disable this feature, add the following JVM property:
- -Dfrank.instrumentation.logContext=false
If true, whenever a parameter value is resolved, an event will be added to the current span.
- frank.instrumentation.parameters=
true|false - default:
true
To disable this feature, add the following JVM property:
- -Dfrank.instrumentation.parameters=false
If true, whenever a pipe is called, a new span is created.
- frank.instrumentation.pipes=
true|false - default:
true
To disable this feature, add the following JVM property:
- -Dfrank.instrumentation.pipes=false
If true, whenever a pipeline is called, a new span is created.
- frank.instrumentation.pipeline=
true|false - default:
true
To disable this feature, add the following JVM property:
- -Dfrank.instrumentation.pipeline=false
If true, whenever a sender is called, a new span is created.
- frank.instrumentation.senders=
true|false - default:
true
To disable this feature, add the following JVM property:
- -Dfrank.instrumentation.senders=false
If true, context is propagated when an IteratorPipe is configured to work in parallel.
- frank.instrumentation.parallel.iterator.propagation=
true|false - default:
true
To disable this feature, add the following JVM property:
- -Dfrank.instrumentation.parallel.iterator.propagation=false
By default the OpenTelemetry agent also traces all traffic towards the Frank Framework API. It might be desired to disable tracing traffic towards these endpoints.
By activating the Frank Framework API sampler, all traffic towards configured endpoints will be ignored.
Set the following environment variable to active the Frank Framework API Sampler
- OTEL_TRACES_SAMPLER=frank_framework_api_sampler
Override the following property to configure the list of endpoints that should be ignored.
- frank.sampler.ignore.http=
comma,separated,list - default:
/iaf/api,/iaf/gui,/testtool
There is a certain overlap of information which is captured, especially when the instrumentation modules are configured in the most verbose modes. There are certain differences between this project and the Ladybug project, the key differences are:
- Ladybug provides capabilities to debug and test the Frank application, i.e: inspect messages, compare reports, etc
- This project is meant to provide compatibility for the Frank Framework with the Open Telemetry standard, which aims to provide a vendor-neutral standard for tracing messages across distributed systems.
- Ladybug is only capable of providing information of a single Frank instance.
- The OpenTelemetry standard is designed to provide information across distrubted systems.
- Ladybug provides full insights on how Frank components are configured, which sessionKeys are available within the session, it is inevitable that personal data is captured and visible for those with access to Ladybug.
- This project only traces the path a message took and aims to provide several configurable options which help to prevent capturing personal data.
- Ladybug should not be used in production due a heavy impact on the memory of the JVM but also due to the verbosity of the information that is captured.
- The OpenTelemetry standard is designed to run in production systems and is used in production by sevaral organisations across the globe.
- https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/contributing/writing-instrumentation-module.md#write-an-instrumentationmodule-step-by-step
- The OpenTelemetry Java agent loads Advice classes inside of its own isolated
AgentClassLoader, but the Advice method bytecode is inlined into the instrumented application classes. - Application classes do not have access to the
AgentClassLoader.