open-telemetry
/
opentelemetry-java-instrumentation
mirror of https://github.com/open-telemetry/opentelemetry-java-instrumentation.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add documentation for available instrumentation customisation options (#2112) 

* Add documentation for available instrumentation customisation options

* Add link to existing example
This commit is contained in:
Nikita Salnikov-Tarnovski 2021-01-25 22:01:56 +02:00 committed by GitHub
parent 59c1034d34
commit 6c76ebf99d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 35 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
examples/distro/README.md
View File

@ -24,3 +24,38 @@ customize that
* [DemoSpanProcessor](custom/src/main/java/com/example/javaagent/DemoSpanProcessor.java) - custom `SpanProcessor`
* [DemoSpanExporter](custom/src/main/java/com/example/javaagent/DemoSpanExporter.java) - custom `SpanExporter`
* [DemoServlet3Instrumentation](instrumentation/servlet-3/src/main/java/com/example/javaagent/instrumentation/DemoServlet3Instrumentation.java) - additional instrumentation
## Instrumentation customisation
There are several options to override or customise instrumentation provided by the upstream agent.
The following description follows one specific use-case:
> Instrumentation X from Otel distribution creates span that I don't like and I want to change it in my vendor distro.
As an example, let us take some database client instrumentation that creates a span for database call
and extracts data from db connection to provide attributes for that span.
### I don't want this span at all
The easiest case. You can just pre-configure your distribution and disable given instrumentation.
### I want to add/modify some attributes and their values does NOT depend on a specific db connection instance.
E.g. you want to add some data from call stack as span attribute.
In this case just provide your custom `SpanProcessor`.
No need for touching instrumentation itself.
### I want to add/modify some attributes and their values depend on a specific db connection instance.
Write a _new_ instrumentation which injects its own advice into the same method as the original one.
Use `getOrder` method to ensure it is run after the original instrumentation.
Now you can augment current span with new information.
See [DemoServlet3Instrumentation](instrumentation/servlet-3/src/main/java/com/example/javaagent/instrumentation/DemoServlet3Instrumentation.java).
### I want to remove some attributes
Write custom exporter or use attribute filtering functionality in Collector.
### I don't like Otel span at all. I want to significantly modify it and its lifecycle
Disable existing instrumentation.
Write a new one, which injects `Advice` into the same (or better) method as the original instrumentation.
Write your own `Advice` for this.
Use existing `Tracer` directly or extend it.
As you have your own `Advice`, you can control which `Tracer` you use.