From 7d35ffaa06c4e4fa33b8f973af0fb8830b9e9687 Mon Sep 17 00:00:00 2001 From: Cuichen Li Date: Mon, 7 Mar 2022 17:48:58 +0800 Subject: [PATCH 1/5] doc: customized auto-instrumentation --- README.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/README.md b/README.md index ef72b4c177..bf240669a7 100644 --- a/README.md +++ b/README.md @@ -215,6 +215,60 @@ The possible values for the annotation can be * `"my-instrumentation"` - name of `Instrumentation` CR instance. * `"false"` - do not inject +#### Use Customized Image for auto-instrumentation injection + +Although the default auto-instrumentation image can handle some mostly used libraries, it may still +miss the ones you need. In this case, you can tell the operator to use your own customized image. + +```yaml +apiVersion: opentelemetry.io/v1alpha1 +kind: Instrumentation +metadata: + name: my-instrumentation +spec: + exporter: + endpoint: http://otel-collector:4317 + propagators: + - tracecontext + - baggage + - b3 + sampler: + type: parentbased_traceidratio + argument: "0.25" + java: + image: your-customized-auto-instrumentation-image:java + nodejs: + image: your-customized-auto-instrumentation-image:nodejs + python: + image: your-customized-auto-instrumentation-image:python +``` + +To build your customized image, you can start with editing the default dockerfiles. They are stored in the `autoinstrumentation` +directory. In general, you should comply with the guidelines below. +- Python + - Ensure the packages are installed in the `/autoinstrumentation` directory. This is required as when instrumenting the pod, + one init container will be created to copy all the content in `/autoinstrumentation` directory to your app's container. Then + update the `PYTHONPATH` environment variable accordingly. To achieve this, you can mimic the one in `autoinstrumentation/python/Dockerfile` + by using multi-stage builds. In the first stage, install all the required packages in one custom directory with `pip install --target`. + Then in the second stage, copy the directory to `/autoinstrumentation`. + - Ensure you have `opentelemetry-distro` and `opentelemetry-instrumentation` installed. Those two packages are essential to + Python auto-instrumentation. + - Grant the necessary access to `/autoinstrumentation` directory. `chmod -R go+r /autoinstrumentation` +- Node.js + - Ensure the packages are installed in the `/autoinstrumentation` directory. This is required as when instrumenting the pod, + one init container will be created to copy all the content in `/autoinstrumentation` directory to your app's container. Then + update the `NODE_OPTIONS` environment variable accordingly. To achieve this, you can mimic the one in `autoinstrumentation/nodejs/Dockerfile` + by using multi-stage builds. In the first stage, install all the required packages in one custom directory. + Then in the second stage, copy the directory to `/autoinstrumentation`. + - Ensure you have `@opentelemetry/api`, `@opentelemetry/auto-instrumentations-node`, and `@opentelemetry/sdk-node` installed. + - Grant the necessary access to `/autoinstrumentation` directory. `chmod -R go+r /autoinstrumentation` +- Java + - Download your customized `javaagent.jar` to `/javaagent.jar`. This is required as when instrumenting the pod, + one init container will be created to copy the jar to your app's container. + - To customize the instrumentation library, you may need fork https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/javaagent + and make changes accordingly. + - Grant the necessary access to the jar. `chmod -R go+r /javaagent.jar` + ## Compatibility matrix ### OpenTelemetry Operator vs. OpenTelemetry Collector From 90a44202e35dfb0387b357cd9c477a1e32d623cc Mon Sep 17 00:00:00 2001 From: Cuichen Li Date: Tue, 8 Mar 2022 09:57:35 +0800 Subject: [PATCH 2/5] doc: update based on comments --- README.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index bf240669a7..3ab2415a32 100644 --- a/README.md +++ b/README.md @@ -243,7 +243,7 @@ spec: image: your-customized-auto-instrumentation-image:python ``` -To build your customized image, you can start with editing the default dockerfiles. They are stored in the `autoinstrumentation` +To build your customized image, you can start with reusing the default dockerfiles. They are stored in the `autoinstrumentation` directory. In general, you should comply with the guidelines below. - Python - Ensure the packages are installed in the `/autoinstrumentation` directory. This is required as when instrumenting the pod, @@ -251,8 +251,8 @@ directory. In general, you should comply with the guidelines below. update the `PYTHONPATH` environment variable accordingly. To achieve this, you can mimic the one in `autoinstrumentation/python/Dockerfile` by using multi-stage builds. In the first stage, install all the required packages in one custom directory with `pip install --target`. Then in the second stage, copy the directory to `/autoinstrumentation`. - - Ensure you have `opentelemetry-distro` and `opentelemetry-instrumentation` installed. Those two packages are essential to - Python auto-instrumentation. + - Ensure you have `opentelemetry-distro` and `opentelemetry-instrumentation` or your customized alternatives installed. + Those two packages are essential to Python auto-instrumentation. - Grant the necessary access to `/autoinstrumentation` directory. `chmod -R go+r /autoinstrumentation` - Node.js - Ensure the packages are installed in the `/autoinstrumentation` directory. This is required as when instrumenting the pod, @@ -260,7 +260,8 @@ directory. In general, you should comply with the guidelines below. update the `NODE_OPTIONS` environment variable accordingly. To achieve this, you can mimic the one in `autoinstrumentation/nodejs/Dockerfile` by using multi-stage builds. In the first stage, install all the required packages in one custom directory. Then in the second stage, copy the directory to `/autoinstrumentation`. - - Ensure you have `@opentelemetry/api`, `@opentelemetry/auto-instrumentations-node`, and `@opentelemetry/sdk-node` installed. + - Ensure you have `@opentelemetry/api`, `@opentelemetry/auto-instrumentations-node`, and `@opentelemetry/sdk-node` or your customized + alternatives installed. - Grant the necessary access to `/autoinstrumentation` directory. `chmod -R go+r /autoinstrumentation` - Java - Download your customized `javaagent.jar` to `/javaagent.jar`. This is required as when instrumenting the pod, From cf57276d8b2f5b5e5a44a8fe9fd3545d9269bf89 Mon Sep 17 00:00:00 2001 From: Cuichen Li Date: Tue, 8 Mar 2022 09:58:09 +0800 Subject: [PATCH 3/5] doc: wording --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3ab2415a32..20c1f59fad 100644 --- a/README.md +++ b/README.md @@ -243,7 +243,7 @@ spec: image: your-customized-auto-instrumentation-image:python ``` -To build your customized image, you can start with reusing the default dockerfiles. They are stored in the `autoinstrumentation` +To build your customized image, you can start by reusing the default dockerfiles. They are stored in the `autoinstrumentation` directory. In general, you should comply with the guidelines below. - Python - Ensure the packages are installed in the `/autoinstrumentation` directory. This is required as when instrumenting the pod, From aca5035de49b59ba94e6cb4f7022ae260c9be5d2 Mon Sep 17 00:00:00 2001 From: Cuichen Li Date: Wed, 9 Mar 2022 20:26:28 +0800 Subject: [PATCH 4/5] doc: update based on comments --- README.md | 41 +++------------------------ autoinstrumentation/java/Dockerfile | 4 +++ autoinstrumentation/nodejs/Dockerfile | 9 ++++++ autoinstrumentation/python/Dockerfile | 10 +++++++ 4 files changed, 27 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 20c1f59fad..870dd7f4c4 100644 --- a/README.md +++ b/README.md @@ -215,10 +215,10 @@ The possible values for the annotation can be * `"my-instrumentation"` - name of `Instrumentation` CR instance. * `"false"` - do not inject -#### Use Customized Image for auto-instrumentation injection +#### Use customized or vendor instrumentation -Although the default auto-instrumentation image can handle some mostly used libraries, it may still -miss the ones you need. In this case, you can tell the operator to use your own customized image. +By default, the operator uses upstream auto-instrumentation libraries. Custom auto-instrumentation can be configured by +overriding the image fields in a CR. ```yaml apiVersion: opentelemetry.io/v1alpha1 @@ -226,15 +226,6 @@ kind: Instrumentation metadata: name: my-instrumentation spec: - exporter: - endpoint: http://otel-collector:4317 - propagators: - - tracecontext - - baggage - - b3 - sampler: - type: parentbased_traceidratio - argument: "0.25" java: image: your-customized-auto-instrumentation-image:java nodejs: @@ -244,31 +235,7 @@ spec: ``` To build your customized image, you can start by reusing the default dockerfiles. They are stored in the `autoinstrumentation` -directory. In general, you should comply with the guidelines below. -- Python - - Ensure the packages are installed in the `/autoinstrumentation` directory. This is required as when instrumenting the pod, - one init container will be created to copy all the content in `/autoinstrumentation` directory to your app's container. Then - update the `PYTHONPATH` environment variable accordingly. To achieve this, you can mimic the one in `autoinstrumentation/python/Dockerfile` - by using multi-stage builds. In the first stage, install all the required packages in one custom directory with `pip install --target`. - Then in the second stage, copy the directory to `/autoinstrumentation`. - - Ensure you have `opentelemetry-distro` and `opentelemetry-instrumentation` or your customized alternatives installed. - Those two packages are essential to Python auto-instrumentation. - - Grant the necessary access to `/autoinstrumentation` directory. `chmod -R go+r /autoinstrumentation` -- Node.js - - Ensure the packages are installed in the `/autoinstrumentation` directory. This is required as when instrumenting the pod, - one init container will be created to copy all the content in `/autoinstrumentation` directory to your app's container. Then - update the `NODE_OPTIONS` environment variable accordingly. To achieve this, you can mimic the one in `autoinstrumentation/nodejs/Dockerfile` - by using multi-stage builds. In the first stage, install all the required packages in one custom directory. - Then in the second stage, copy the directory to `/autoinstrumentation`. - - Ensure you have `@opentelemetry/api`, `@opentelemetry/auto-instrumentations-node`, and `@opentelemetry/sdk-node` or your customized - alternatives installed. - - Grant the necessary access to `/autoinstrumentation` directory. `chmod -R go+r /autoinstrumentation` -- Java - - Download your customized `javaagent.jar` to `/javaagent.jar`. This is required as when instrumenting the pod, - one init container will be created to copy the jar to your app's container. - - To customize the instrumentation library, you may need fork https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/javaagent - and make changes accordingly. - - Grant the necessary access to the jar. `chmod -R go+r /javaagent.jar` +directory. In general, you should comply with the guidelines described in the dockerfiles under the `autoinstrumentation` directory. ## Compatibility matrix diff --git a/autoinstrumentation/java/Dockerfile b/autoinstrumentation/java/Dockerfile index 5f143336e8..c33093b871 100644 --- a/autoinstrumentation/java/Dockerfile +++ b/autoinstrumentation/java/Dockerfile @@ -1,3 +1,7 @@ +# To build one auto-instrumentation image for Java, please: +# - Download your customized `javaagent.jar` to `/javaagent.jar`. This is required as when instrumenting the pod, +# one init container will be created to copy the jar to your app's container. +# - Grant the necessary access to the jar. `chmod -R go+r /javaagent.jar` FROM busybox ARG version diff --git a/autoinstrumentation/nodejs/Dockerfile b/autoinstrumentation/nodejs/Dockerfile index cd648ccea2..1e0fd96f9b 100644 --- a/autoinstrumentation/nodejs/Dockerfile +++ b/autoinstrumentation/nodejs/Dockerfile @@ -1,3 +1,12 @@ +# To build one auto-instrumentation image for Node.js, please: +# - Ensure the packages are installed in the `/autoinstrumentation` directory. This is required as when instrumenting the pod, +# one init container will be created to copy all the content in `/autoinstrumentation` directory to your app's container. Then +# update the `NODE_OPTIONS` environment variable accordingly. To achieve this, you can mimic the one in `autoinstrumentation/nodejs/Dockerfile` +# by using multi-stage builds. In the first stage, install all the required packages in one custom directory. +# Then in the second stage, copy the directory to `/autoinstrumentation`. +# - Ensure you have `@opentelemetry/api`, `@opentelemetry/auto-instrumentations-node`, and `@opentelemetry/sdk-node` or your customized +# alternatives installed. +# - Grant the necessary access to `/autoinstrumentation` directory. `chmod -R go+r /autoinstrumentation` FROM node:16 AS build WORKDIR /operator-build diff --git a/autoinstrumentation/python/Dockerfile b/autoinstrumentation/python/Dockerfile index 8086afe0a6..5355ed2777 100644 --- a/autoinstrumentation/python/Dockerfile +++ b/autoinstrumentation/python/Dockerfile @@ -1,3 +1,13 @@ +# To build one auto-instrumentation image for Python, please: +# - Ensure the packages are installed in the `/autoinstrumentation` directory. This is required as when instrumenting the pod, +# one init container will be created to copy all the content in `/autoinstrumentation` directory to your app's container. Then +# update the `PYTHONPATH` environment variable accordingly. To achieve this, you can mimic the one in `autoinstrumentation/python/Dockerfile` +# by using multi-stage builds. In the first stage, install all the required packages in one custom directory with `pip install --target`. +# Then in the second stage, copy the directory to `/autoinstrumentation`. +# - Ensure you have `opentelemetry-distro` and `opentelemetry-instrumentation` or your customized alternatives installed. +# Those two packages are essential to Python auto-instrumentation. +# - Grant the necessary access to `/autoinstrumentation` directory. `chmod -R go+r /autoinstrumentation` + FROM python:3.10-alpine AS build WORKDIR /operator-build From 9e2875d155d2829ebf76d49074dadb8488b739d4 Mon Sep 17 00:00:00 2001 From: Cuichen Li Date: Tue, 15 Mar 2022 09:33:15 +0800 Subject: [PATCH 5/5] doc: update based on comments --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 870dd7f4c4..74c74e6433 100644 --- a/README.md +++ b/README.md @@ -234,8 +234,8 @@ spec: image: your-customized-auto-instrumentation-image:python ``` -To build your customized image, you can start by reusing the default dockerfiles. They are stored in the `autoinstrumentation` -directory. In general, you should comply with the guidelines described in the dockerfiles under the `autoinstrumentation` directory. +The Dockerfiles for auto-instrumentation can be found in [autoinstrumentation directory](./autoinstrumentation). +Follow the instructions in the Dockerfiles on how to build a custom container image. ## Compatibility matrix