diff --git a/examples/distro/README.md b/examples/distro/README.md
index 5b0ffa63d6..5f188fdbf6 100644
--- a/examples/distro/README.md
+++ b/examples/distro/README.md
@@ -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.
\ No newline at end of file