|
| 1 | +--- |
| 2 | +description: SUSE Observability |
| 3 | +--- |
| 4 | + |
| 5 | +# Getting Started with Open Telemetry |
| 6 | + |
| 7 | +Here is the setup we'll be creating, for an application that needs to be monitored: |
| 8 | + |
| 9 | +* The monitored application / workload running on a Linux box |
| 10 | +* The Open Telemetry collector running on the same Linux box |
| 11 | +* SUSE Observability or SUSE Cloud Observability |
| 12 | + |
| 13 | +TODO: Replace with inline basic collector config (also possible to run a single collector for multiple applications on different nodes), that includes references to URL and link to ingress docs for self-hosted |
| 14 | +TODO: Also inline collector setup for Kubernetes that uses a minimal config? Link to separate collector config page to explain the details and customizations (next todo) |
| 15 | +TODO: Create separate page on more detailed config (the existing collector.md minus the Kubernetes installation guide, with separate sections for customizations like sampling, host metrics) |
| 16 | +TODO: Also inlince the collector setup for AWS getting started |
| 17 | +TODO: Only define one exporter, refer to troubleshooting / collector config to switch to http exporter |
| 18 | + |
| 19 | +DIAGRAM... |
| 20 | + |
| 21 | +## Install the Open Telemetry collector |
| 22 | + |
| 23 | +{% hint type="info" %} |
| 24 | +For a production setup it is strongly recommended to install the collector, since it allows your service to offload data quickly and the collector can take care of additional handling like retries, batching, encryption or even sensitive data filtering. |
| 25 | +{% endhint %} |
| 26 | + |
| 27 | +First we'll install the collector. We configure it to: |
| 28 | + |
| 29 | +* Receive data from, potentially many, instrumented applications |
| 30 | +* Enrich collected data with host attributes |
| 31 | +* Generate metrics for traces |
| 32 | +* Forward the data to SUSE Observability, including authentication using the API key |
| 33 | + |
| 34 | +Next to that it will also retry sending data when there are a connection problems. |
| 35 | + |
| 36 | +### Configure and install the collector |
| 37 | + |
| 38 | +### Install and configure the collector |
| 39 | + |
| 40 | +The collector provides packages (apk, deb and rpm) for most Linux versions and architectures and it uses `systemd` for automatic service configuration. To install it find the [latest release on Github](https://github.com/open-telemetry/opentelemetry-collector-releases/releases) and update the URL in the example to use the latest version: |
| 41 | + |
| 42 | +{% tabs %} |
| 43 | +{% tab title="DEB AMD64" %} |
| 44 | +```bash |
| 45 | +wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.123.0/otelcol_0.123.0_linux_amd64.deb |
| 46 | +sudo dpkg -i otelcol_0.123.0_linux_amd64.deb |
| 47 | +``` |
| 48 | +{% endtab %} |
| 49 | +{% tab title="DEB ARM64" %} |
| 50 | +```bash |
| 51 | +wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.123.0/otelcol_0.123.0_linux_arm64.deb |
| 52 | +sudo dpkg -i otelcol_0.123.0_linux_arm64.deb |
| 53 | +``` |
| 54 | +{% endtab %} |
| 55 | +{% tab title="RPM ARM64" %} |
| 56 | +```bash |
| 57 | +wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.123.0/otelcol_0.123.0_linux_amd64.rpm |
| 58 | +sudo rpm -ivh otelcol_0.123.0_linux_amd64.rpm |
| 59 | +``` |
| 60 | +{% endtab %} |
| 61 | +{% tab title="RPM ARM64" %} |
| 62 | +```bash |
| 63 | +wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.123.0/otelcol_0.123.0_linux_arm64.rpm |
| 64 | +sudo rpm -ivh otelcol_0.123.0_linux_arm64.rpm |
| 65 | +``` |
| 66 | +{% endtab %} |
| 67 | +{% endtabs %} |
| 68 | + |
| 69 | +For other installation options use the [Open Telemetry instructions](https://opentelemetry.io/docs/collector/installation/#linux). |
| 70 | + |
| 71 | +After installation modify the collector configuration by editing `/etc/otelcol/config.yaml`. Change the file such that it looks like the `config.yaml` example here, replace `<otlp-suse-observability-endpoint>` with your OTLP endpoint (see [OTLP API](../otlp-apis.md) for your endpoint) and insert your receiver api key (see [here](/use/security/k8s-ingestion-api-keys.md#api-keys) where to find it) for `<<receiver-api-key>`: |
| 72 | + |
| 73 | +{% code title="config.yaml" lineNumbers="true" %} |
| 74 | +```yaml |
| 75 | +receivers: |
| 76 | + otlp: |
| 77 | + protocols: |
| 78 | + # Only bind to localhost to keep the collector secure |
| 79 | + grpc: |
| 80 | + endpoint: 127.0.0.1:4317 |
| 81 | + http: |
| 82 | + endpoint: 127.0.0.1:4318 |
| 83 | +extensions: |
| 84 | + # Use the API key from the env far for authentication |
| 85 | + bearertokenauth: |
| 86 | + scheme: SUSEObservability |
| 87 | + token: "<receiver-api-key>" |
| 88 | +exporters: |
| 89 | + otlp/suse-observability: |
| 90 | + auth: |
| 91 | + authenticator: bearertokenauth |
| 92 | + # Put in your own otlp endpoint |
| 93 | + endpoint: <otlp-suse-observability-endpoint> |
| 94 | +processors: |
| 95 | + memory_limiter: |
| 96 | + check_interval: 5s |
| 97 | + limit_percentage: 80 |
| 98 | + spike_limit_percentage: 25 |
| 99 | + batch: |
| 100 | + # Optionally include resource information from the system running the collector |
| 101 | + resourcedetection/system: |
| 102 | + detectors: [env, system] # Replace system with gcp, ec2, azure when running in cloud environments |
| 103 | + system: |
| 104 | + hostname_sources: ["os"] |
| 105 | +connectors: |
| 106 | + # Generate metrics for spans |
| 107 | + spanmetrics: |
| 108 | + metrics_expiration: 5m |
| 109 | + namespace: otel_span |
| 110 | +service: |
| 111 | + extensions: |
| 112 | + - health_check |
| 113 | + - bearertokenauth |
| 114 | + pipelines: |
| 115 | + traces: |
| 116 | + receivers: [otlp] |
| 117 | + processors: [memory_limiter, resourcedetection/system, batch] |
| 118 | + exporters: [debug, spanmetrics, otlp/suse-observability] |
| 119 | + metrics: |
| 120 | + receivers: [otlp, spanmetrics, prometheus] |
| 121 | + processors: [memory_limiter, batch, resourcedetection/system] |
| 122 | + exporters: [debug, otlp/suse-observability] |
| 123 | +``` |
| 124 | +{% endcode %} |
| 125 | +
|
| 126 | +Finally restart the collector: |
| 127 | +
|
| 128 | +```bash |
| 129 | +sudo systemctl restart otelcol |
| 130 | +``` |
| 131 | + |
| 132 | +To see the logs of the collector use: |
| 133 | +```bash |
| 134 | +sudo journalctl otelcol |
| 135 | +``` |
| 136 | + |
| 137 | +## Collect telemetry data from your application |
| 138 | + |
| 139 | +The common way to collect telemetry data is to instrument your application using the Open Telemetry SDK's. We've documented some quick start guides for a few languages, but there are many more: |
| 140 | +* [Java](languages/java.md) |
| 141 | +* [.NET](languages/dot-net.md) |
| 142 | +* [Node.js](languages/node.js.md) |
| 143 | + |
| 144 | +No additional configuration is needed for the SDKs, they export to localhost via OTLP or OTLP over HTTP (depending on the supported protocols) by default. |
| 145 | + |
| 146 | +For other languages follow the documentation on [opentelemetry.io](https://opentelemetry.io/docs/languages/). |
| 147 | + |
| 148 | +## View the results |
| 149 | +Go to SUSE Observability and make sure the Open Telemetry Stackpack is installed (via the main menu -> Stackpacks). |
| 150 | + |
| 151 | +After a a short while and if your application is processing some traffic you should be able to find it under its service name in the Open Telemetry -> services and service instances overviews. Traces will appear in the [trace explorer](/use/traces/k8sTs-explore-traces.md) and in the [trace perspective](/use/views/k8s-traces-perspective.md) for the service and service instance components. Span metrics and language specific metrics (if available) will become available in the [metrics perspective](/use/views/k8s-metrics-perspective.md) for the components. |
0 commit comments