Update getting-started.md docs

Add polish, improve the grammar and mechanics, ensure consistency, and refine the flow of the document.
open-telemetry · Jan 22, 2025 · 1331121 · 1331121
1 parent 5e1504c
commit 1331121
Showing 1 changed file with 86 additions and 77 deletions.
diff --git 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: <location_of_target_application_binary>
+       - name: OTEL_EXPORTER_OTLP_ENDPOINT
+         value: "http://<address_in_network>:4318"
+       - name: OTEL_SERVICE_NAME
+         value: "<name_of_service>"
+     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://<address_in_docker_network>:4318
+       - OTEL_GO_AUTO_TARGET_EXE=<location_of_target_application_binary>
+       - OTEL_SERVICE_NAME=<name_of_your_application>
+       - OTEL_PROPAGATORS=tracecontext,baggage
+     volumes:
+       - <shared_volume_of_application>
+       - /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://<address_in_docker_network>:4318
-        - OTEL_GO_AUTO_TARGET_EXE=<location_of_target_application_binary>
-        - OTEL_SERVICE_NAME=<name_of_your_application>
-        - OTEL_PROPAGATORS=tracecontext,baggage
-      volumes:
-        - <shared_volume_of_application>
-        - /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: <location_of_target_application_binary>
-       - name: OTEL_EXPORTER_OTLP_ENDPOINT
-         value: "http://<address_in_network>:4318"
-       - name: OTEL_SERVICE_NAME
-         value: "<name_of_service>"
-     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.