|
| 1 | +## Quick Start For Local Telemetry |
| 2 | + |
| 3 | +To quickly setup a local telemetry environment where OpenTelemetry data is sent to a local instance of Grafana LGTM: |
| 4 | +1. start the [Grafana LGTM docker image](https://hub.docker.com/r/grafana/otel-lgtm): |
| 5 | +```shell |
| 6 | +docker run -p 3000:3000 -p 4317:4317 -p 4318:4318 --rm -ti grafana/otel-lgtm |
| 7 | +``` |
| 8 | +2. create a basic OpenTelemetry configuration file which will send data to the local instance of Grafana LGTM: |
| 9 | +```yaml |
| 10 | +resource: |
| 11 | + attributes: |
| 12 | + - name: service.name |
| 13 | + value: my_app_name |
| 14 | +tracer_provider: |
| 15 | + processors: |
| 16 | + - simple: # NOTE: you should use batch in production! |
| 17 | + exporter: |
| 18 | + otlp: |
| 19 | + protocol: grpc |
| 20 | + endpoint: http://localhost:4317 |
| 21 | +meter_provider: |
| 22 | + readers: |
| 23 | + - periodic: |
| 24 | + interval: 100 # 100 milliseconds, use something longer in production! |
| 25 | + exporter: |
| 26 | + otlp: |
| 27 | + protocol: grpc |
| 28 | + endpoint: http://localhost:4317 |
| 29 | +logger_provider: |
| 30 | + processors: |
| 31 | + - simple: # NOTE: you should use batch in production! |
| 32 | + exporter: |
| 33 | + otlp: |
| 34 | + protocol: grpc |
| 35 | + endpoint: http://localhost:4317 |
| 36 | +``` |
| 37 | +3. set the `OTEL_EXPERIMENTAL_CONFIG_FILE` environment variable to the path of the configuration file: |
| 38 | +`export OTEL_EXPERIMENTAL_CONFIG_FILE=path/to/config.yaml` |
| 39 | +4. start your application or tests |
| 40 | +5. view the data in Grafana LGTM at http://localhost:3000/. The Drilldown views are suggested for getting started. |
| 41 | + |
| 42 | +## OpenTelemetry Initialization |
| 43 | + |
| 44 | +While manual OpenTelemetry initialization is still supported, this package provides a single |
| 45 | +point of initialization such that end users can just use the official |
| 46 | +OpenTelemetry declarative configuration spec: https://opentelemetry.io/docs/languages/sdk-configuration/declarative-configuration/ |
| 47 | +End users only need to set the `OTEL_EXPERIMENTAL_CONFIG_FILE` environment variable to the path of |
| 48 | +an OpenTelemetry configuration file and that's it. |
| 49 | +All the documentation necessary is provided in the OpenTelemetry documentation. |
| 50 | + |
| 51 | +## Developer Usage |
| 52 | + |
| 53 | +Developers need to do two things to use this package properly: |
| 54 | + 1. Import this package before declaring any otel Tracer, Meter or Logger instances. |
| 55 | + 2. Make sure Shutdown() is called when the application is shutting down. |
| 56 | + Tests can use the TestingInit function at startup to accomplish this. |
| 57 | + |
| 58 | +If these steps are followed, developers can follow the official golang otel conventions |
| 59 | +of declaring package-level tracer and meter instances using otel.Tracer() and otel.Meter(). |
| 60 | +NOTE: it is important to thread context.Context properly for spans, metrics and logs to be |
| 61 | +correlated correctly. |
| 62 | +When using the SDK's context type, spans must be started with Context.StartSpan to |
| 63 | +get an SDK context which has the span set correctly. |
| 64 | +For logging, go.opentelemetry.io/contrib/bridges/otelslog provides a way to do this with the standard |
| 65 | +library slog package. |
0 commit comments