Skip to content

Commit ba5dfff

Browse files
rb3ckersrb3ckers
committed
STAC-22435 Document linux installation
1 parent 02d1fb6 commit ba5dfff

File tree

5 files changed

+155
-54
lines changed

5 files changed

+155
-54
lines changed

‎SUMMARY.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,7 @@
9595
* [Getting started](setup/otel/getting-started/README.md)
9696
* [Rancher & Kubernetes](setup/otel/getting-started/getting-started-k8s.md)
9797
* [AWS Lambda](setup/otel/getting-started/getting-started-lambda.md)
98-
* [Other](setup/otel/getting-started/getting-started-other.md)
98+
* [Linux](setup/otel/getting-started/getting-started-linux.md)
9999
* [Open telemetry collector](setup/otel/collector.md)
100100
* [Collector as a proxy](setup/otel/proxy-collector.md)
101101
* [Languages](setup/otel/languages/README.md)

‎setup/otel/collector.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,10 @@ config:
7575
authenticator: bearertokenauth
7676
endpoint: https://<otlp--http-stackstate-endpoint>
7777
processors:
78+
memory_limiter:
79+
check_interval: 5s
80+
limit_percentage: 80
81+
spike_limit_percentage: 25
7882
tail_sampling:
7983
decision_wait: 10s
8084
policies:

‎setup/otel/getting-started/getting-started-k8s.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,11 @@ config:
8585
# Put in your own otlp endpoint
8686
endpoint: <otlp-suse-observability-endpoint>
8787
processors:
88+
memory_limiter:
89+
check_interval: 5s
90+
limit_percentage: 80
91+
spike_limit_percentage: 25
92+
batch:
8893
resource:
8994
attributes:
9095
- key: k8s.cluster.name

‎setup/otel/getting-started/getting-started-linux.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
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+
DIAGRAM...
14+
15+
## Install the Open Telemetry collector
16+
17+
{% hint type="info" %}
18+
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.
19+
{% endhint %}
20+
21+
First we'll install the collector. We configure it to:
22+
23+
* Receive data from, potentially many, instrumented applications
24+
* Enrich collected data with host attributes
25+
* Generate metrics for traces
26+
* Forward the data to SUSE Observability, including authentication using the API key
27+
28+
Next to that it will also retry sending data when there are a connection problems.
29+
30+
### Configure and install the collector
31+
32+
### Install and configure the collector
33+
34+
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:
35+
36+
{% tabs %}
37+
{% tab title="DEB AMD64" %}
38+
```bash
39+
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.123.0/otelcol_0.123.0_linux_amd64.deb
40+
sudo dpkg -i otelcol_0.123.0_linux_amd64.deb
41+
```
42+
{% endtab %}
43+
{% tab title="DEB ARM64" %}
44+
```bash
45+
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.123.0/otelcol_0.123.0_linux_arm64.deb
46+
sudo dpkg -i otelcol_0.123.0_linux_arm64.deb
47+
```
48+
{% endtab %}
49+
{% tab title="RPM ARM64" %}
50+
```bash
51+
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.123.0/otelcol_0.123.0_linux_amd64.rpm
52+
sudo rpm -ivh otelcol_0.123.0_linux_amd64.rpm
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_arm64.rpm
58+
sudo rpm -ivh otelcol_0.123.0_linux_arm64.rpm
59+
```
60+
{% endtab %}
61+
{% endtabs %}
62+
63+
For other installation options use the [Open Telemetry instructions](https://opentelemetry.io/docs/collector/installation/#linux).
64+
65+
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>`:
66+
67+
{% code title="config.yaml" lineNumbers="true" %}
68+
```yaml
69+
receivers:
70+
otlp:
71+
protocols:
72+
# Only bind to localhost to keep the collector secure
73+
grpc:
74+
endpoint: 127.0.0.1:4317
75+
http:
76+
endpoint: 127.0.0.1:4318
77+
extensions:
78+
# Use the API key from the env far for authentication
79+
bearertokenauth:
80+
scheme: SUSEObservability
81+
token: "<receiver-api-key>"
82+
exporters:
83+
otlp/suse-observability:
84+
auth:
85+
authenticator: bearertokenauth
86+
# Put in your own otlp endpoint
87+
endpoint: <otlp-suse-observability-endpoint>
88+
processors:
89+
memory_limiter:
90+
check_interval: 5s
91+
limit_percentage: 80
92+
spike_limit_percentage: 25
93+
batch:
94+
# Optionally include resource information from the system running the collector
95+
resourcedetection/system:
96+
detectors: [env, system] # Replace system with gcp, ec2, azure when running in cloud environments
97+
system:
98+
hostname_sources: ["os"]
99+
connectors:
100+
# Generate metrics for spans
101+
spanmetrics:
102+
metrics_expiration: 5m
103+
namespace: otel_span
104+
service:
105+
extensions:
106+
- health_check
107+
- bearertokenauth
108+
pipelines:
109+
traces:
110+
receivers: [otlp]
111+
processors: [memory_limiter, resourcedetection/system, batch]
112+
exporters: [debug, spanmetrics, otlp/suse-observability]
113+
metrics:
114+
receivers: [otlp, spanmetrics, prometheus]
115+
processors: [memory_limiter, batch, resourcedetection/system]
116+
exporters: [debug, otlp/suse-observability]
117+
```
118+
{% endcode %}
119+
120+
Finally restart the collector:
121+
122+
```bash
123+
sudo systemctl restart otelcol
124+
```
125+
126+
To see the logs of the collector use:
127+
```bash
128+
sudo journalctl otelcol
129+
```
130+
131+
## Collect telemetry data from your application
132+
133+
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:
134+
* [Java](languages/java.md)
135+
* [.NET](languages/dot-net.md)
136+
* [Node.js](languages/node.js.md)
137+
138+
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.
139+
140+
For other languages follow the documentation on [opentelemetry.io](https://opentelemetry.io/docs/languages/).
141+
142+
## View the results
143+
Go to SUSE Observability and make sure the Open Telemetry Stackpack is installed (via the main menu -> Stackpacks).
144+
145+
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.

‎setup/otel/getting-started/getting-started-other.md‎

Lines changed: 0 additions & 53 deletions
This file was deleted.

0 commit comments

Comments
 (0)