diff --git a/docs/getting-started.md b/docs/getting-started.md index 7a7540fab..adbe8ded1 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,105 +1,114 @@ -## Get started +# Getting Started with OpenTelemetry Go Automatic Instrumentation -You can instrument a Go executable using OpenTelemetry without having -to write additional code. All you need to do is configure a few environment -variables and run the instrumentation with elevated privileges. +You can instrument a Go executable using OpenTelemetry without writing additional code. +All you need to do is configure a few environment variables and run the instrumentation with elevated privileges. -The following example shows how to instrument a Go application -automatically on a Linux host, through Docker, and using Kubernetes. +This guide demonstrates how to automatically instrument a Go application in Kubernetes, using Docker, and on a Linux host. -### Prerequisites +## Instrument an Application in Kubernetes -To instrument an application automatically, you need the following: +To instrument an application running in Kubernetes, follow these steps: -- Linux with kernel version 4.19 or higher -- x64 or ARM processor -- Docker image or compiled binary of OpenTelemetry Go Automatic Instrumentation -- Go 1.18 or higher +1. **Update your Kubernetes manifest**: -To compile the instrumentation binary, run `make build`. + - Add the OpenTelemetry Go Automatic Instrumentation container image. + - Ensure `runAsUser` is set to `0` and `privileged` is set to `true`. -### Instrument an application on the same host + Example: -To instrument an application on the same host, follow these steps: + ```yaml + - name: autoinstrumentation-go + image: otel/autoinstrumentation-go + imagePullPolicy: IfNotPresent + env: + - name: OTEL_GO_AUTO_TARGET_EXE + value: + - name: OTEL_EXPORTER_OTLP_ENDPOINT + value: "http://:4318" + - name: OTEL_SERVICE_NAME + value: "" + securityContext: + runAsUser: 0 + privileged: true + ``` -1. Run the target application. +2. **Verify `shareProcessNamespace` is enabled**: -2. Set the following environment variables before running the instrumentation: + - Check if the `shareProcessNamespace` configuration is present in the pod spec. + Add it if missing. Refer to the [Kubernetes documentation](https://kubernetes.io/docs/tasks/configure-pod-container/share-process-namespace/). - - `OTEL_GO_AUTO_TARGET_EXE`: Full path of the executable you want to - instrument. For example, `/home/bin/service_executable` - - `OTEL_SERVICE_NAME`: Name of your service or application - - `OTEL_EXPORTER_OTLP_ENDPOINT`: Your observability backend. For example, - `http://localhost:4318`. +3. **Deploy the application** and the instrumentation using the updated manifest. - For example: +## Instrument an Application in Docker Compose - ```sh - sudo OTEL_GO_AUTO_TARGET_EXE=/home/bin/service_executable OTEL_SERVICE_NAME=my_service OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 ./otel-go-instrumentation - ``` +To instrument a containerized application, follow these steps: -3. Run the OpenTelemetry Go Automatic Instrumentation with root privileges. +1. **Modify your `docker-compose.yaml` file**: -> **Note** -> If the target application isn't running yet, the instrumentation waits for -> the process to start. + - Add a Docker network, a shared volume, and a service for your application. -### Instrument an application in Docker Compose +2. **Add a new service for the instrumentation**: -To instrument a containerized application, follow these steps: + ```yaml + go-auto: + image: otel/autoinstrumentation-go + privileged: true + pid: "host" + environment: + - OTEL_EXPORTER_OTLP_ENDPOINT=http://:4318 + - OTEL_GO_AUTO_TARGET_EXE= + - OTEL_SERVICE_NAME= + - OTEL_PROPAGATORS=tracecontext,baggage + volumes: + - + - /proc:/host/proc + ``` -1. Create or edit the docker-compose.yaml file. Make sure to add a Docker -network, a shared volume, and a service for the application. - -2. Edit the docker-compose file to add a new service for the instrumentation: - - ```yaml - go-auto: - image: otel/autoinstrumentation-go - privileged: true - pid: "host" - environment: - - OTEL_EXPORTER_OTLP_ENDPOINT=http://:4318 - - OTEL_GO_AUTO_TARGET_EXE= - - OTEL_SERVICE_NAME= - - OTEL_PROPAGATORS=tracecontext,baggage - volumes: - - - - /proc:/host/proc + For more environment variables, refer to the [OpenTelemetry SDK configuration documentation](https://opentelemetry.io/docs/languages/sdk-configuration/). + +3. **Start the instrumentation** by running: + + ```sh + docker compose up + ``` + +## Instrument an Application on the Same Host + +Follow these steps to instrument an application running on the same host: + +### Prerequisites + +Ensure you have the following: + +- **Linux**: Kernel version 4.19 or higher +- **Processor**: x64 or ARM +- **Go**: Version 1.18 or higher +- **Instrumentation Binary**: Compile the OpenTelemetry Go Automatic Instrumentation binary by running: + + ```sh + make build ``` - For more environment variables, refer to [here](https://opentelemetry.io/docs/languages/sdk-configuration/). +### Steps -3. Run `docker compose up`. +1. **Start the target application.** -### Instrument an application in Kubernetes +2. **Set environment variables** before running the instrumentation: -To instrument an application running in Kubernetes, follow these steps: + - `OTEL_GO_AUTO_TARGET_EXE`: Full path to the executable to instrument. Example: `/home/bin/service_executable` + - `OTEL_SERVICE_NAME`: Name of your service or application + - `OTEL_EXPORTER_OTLP_ENDPOINT`: Observability backend endpoint. Example: `http://localhost:4318` -1. Add the container image of the OpenTelemetry Go Automatic Instrumentation to your manifest. Make sure that `runAsUser` is set to `0`, `privileged` is set to `true`: +3. **Run the OpenTelemetry Go Automatic Instrumentation** with root privileges. - ```yaml - - name: autoinstrumentation-go - image: otel/autoinstrumentation-go - imagePullPolicy: IfNotPresent - env: - - name: OTEL_GO_AUTO_TARGET_EXE - value: - - name: OTEL_EXPORTER_OTLP_ENDPOINT - value: "http://:4318" - - name: OTEL_SERVICE_NAME - value: "" - securityContext: - runAsUser: 0 - privileged: true - ``` -2. Check if the configuration [shareProcessNamespace](https://kubernetes.io/docs/tasks/configure-pod-container/share-process-namespace/) is present in the pod spec, if not, please add it. + > **Note**: If the target application is not running, the instrumentation will wait for the process to start. + + Example command: -3. Deploy the application and the instrumentation using the manifest. + ```sh + sudo OTEL_GO_AUTO_TARGET_EXE=/home/bin/service_executable OTEL_SERVICE_NAME=my_service OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 ./otel-go-instrumentation + ``` -### Configuration +## Configuration -See the documentation for -[`InstrumentationOption`](https://pkg.go.dev/go.opentelemetry.io/auto#InstrumentationOption) -factory functions for information about how to configure the OpenTelemetry Go -Automatic Instrumentation. +For additional configuration options, refer to the [`InstrumentationOption`](https://pkg.go.dev/go.opentelemetry.io/auto#InstrumentationOption) factory functions in the OpenTelemetry Go Automatic Instrumentation documentation.