From 9f038d5715ba181e81f009ff5897e31fc6bdcfb0 Mon Sep 17 00:00:00 2001 From: Remco Beckers Date: Fri, 18 Apr 2025 15:40:34 +0200 Subject: [PATCH 1/5] Add otel operator getting started --- .../open-telemetry-kubernetes-operator.png | Bin 0 -> 92279 bytes SUMMARY.md | 3 +- .../getting-started-k8s-operator.md | 307 ++++++++++++++++++ .../getting-started/getting-started-k8s.md | 4 +- .../getting-started/getting-started-lambda.md | 2 +- 5 files changed, 312 insertions(+), 4 deletions(-) create mode 100644 .gitbook/assets/otel/open-telemetry-kubernetes-operator.png create mode 100644 setup/otel/getting-started/getting-started-k8s-operator.md diff --git a/.gitbook/assets/otel/open-telemetry-kubernetes-operator.png b/.gitbook/assets/otel/open-telemetry-kubernetes-operator.png new file mode 100644 index 0000000000000000000000000000000000000000..9315f857d31269d88965ce09385fbf340559963c GIT binary patch literal 92279 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
=j||& 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 Xx5tcs*_T?1V1v;=dMH=#)V2QsD`~!@ literal 0 HcmV?d00001 diff --git a/SUMMARY.md b/SUMMARY.md index 53159727c..d7dba026d 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -96,7 +96,8 @@ * [Overview](setup/otel/overview.md) * [Getting started](setup/otel/getting-started/README.md) * [Concepts](setup/otel/concepts.md) - * [Rancher & Kubernetes](setup/otel/getting-started/getting-started-k8s.md) + * [Kubernetes](setup/otel/getting-started/getting-started-k8s.md) + * [Kubernetes Operator](setup/otel/getting-started/getting-started-k8s-operator.md) * [Linux](setup/otel/getting-started/getting-started-linux.md) * [AWS Lambda](setup/otel/getting-started/getting-started-lambda.md) * [Open telemetry collector](setup/otel/collector.md) diff --git a/setup/otel/getting-started/getting-started-k8s-operator.md b/setup/otel/getting-started/getting-started-k8s-operator.md new file mode 100644 index 000000000..69f8abeb6 --- /dev/null +++ b/setup/otel/getting-started/getting-started-k8s-operator.md @@ -0,0 +1,307 @@ +--- +description: SUSE Observability +--- + +# Getting Started with Open Telemetry operator on Kubernetes + +Here is the setup we'll be creating, for an application that needs to be monitored: + +* The monitored application / workload running in cluster A, auto-instrumented by the operator +* The Open Telemetry operator in cluster A +* A collector created by the operator +* SUSE Observability running in cluster B, or SUSE Cloud Observability + +![Container instrumentation with Open Telemetry operator auto-instrumentation](/.gitbook/assets/otel/open-telemetry-kubernetes-operator.png) + +## Install the operator + +The Open Telemetry operator offers some extra features over the normal Kubernetes setup: +* It can auto-instrument your application pods for supported languages (Java, .NET, Python, Golang, Node.js), without having to modify the applications or docker images at all +* It can be dropped in as a replacement for the Prometheus operator and start scraping Prometheus exporter endpoints based on service and pod monitors + +### Create the namespace and a secret for the API key + +We'll install in the `open-telemetry` namespace and use the receiver API key generated during installation (see [here](/use/security/k8s-ingestion-api-keys.md#api-keys) where to find it): + +```bash +kubectl create namespace open-telemetry +kubectl create secret generic open-telemetry-collector \ + --namespace open-telemetry \ + --from-literal=API_KEY='' +``` + +### Configure & Install the operator + +The operator is installed with a Helm chart, so first configure the chart repository. + +```bash +helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts +``` + +Let's create a `otel-operator.yaml` file to configure the operator: + +{% code title="otel-operator.yaml" lineNumbers="true" %} +```yaml +# Add image pull secret for private registries +imagePullSecrets: [] +manager: + image: + # Uses chart.appVersion for the tag + repository: ghcr.io/open-telemetry/opentelemetry-operator/opentelemetry-operator + collectorImage: + # find the latest collector releases at https://github.com/open-telemetry/opentelemetry-collector-releases/releases + repository: + ghcr.io/open-telemetry/opentelemetry-collector-k8s + tag: 0.123.1 + targetAllocatorImage: + repository: "" + tag: "" + # Only needed when overriding the image repository, make sure to always specify both the image and tag: + autoInstrumentationImage: + java: + repository: "" + tag: "" + nodejs: + repository: "" + tag: "" + python: + repository: "" + tag: "" + dotnet: + repository: "" + tag: "" + # The Go instrumentation support in the operator is disabled by default. + # To enable it, use the operator.autoinstrumentation.go feature gate. + go: + repository: "" + tag: "" + +admissionWebhooks: + # A production setup should use certManager to generate the certificate, without certmanager the certificate will be generated during the Helm install + certManager: + enabled: false + # The operator has validation and mutation hooks that need a certificate, with this we generate that automatically + autoGenerateCert: + enabled: true +``` +{% endcode %} + +Now install the collector, using the configuration file: + +```bash +helm upgrade --install opentelemetry-operator open-telemetry/opentelemetry-operator \ + --namespace open-telemetry \ + --values otel-operator.yaml +``` + +This only installs the operator. Continue to install the collector and enable auto-instrumentation. + +## The Open Telemetry collector + +The operator manages one or more collector deployments via a Kubernetes custom resource of kind `OpenTelemetryCollector`. We'll create one using the same configuration as used in the [Kubernetes getting started guide](./getting-started-k8s.md). + +It uses the secret created earlier in the guide. Make sure to replace `` with your OTLP endpoint (see [OTLP API](../otlp-apis.md) for your endpoint) and insert the name for your Kubernetes cluster instead of ``: + +{% code title="collector.yaml" lineNumbers="true" %} +```yaml +apiVersion: opentelemetry.io/v1beta1 +kind: OpenTelemetryCollector +metadata: + name: otel-collector +spec: + mode: deployment + envFrom: + - secretRef: + name: open-telemetry-collector + # optional service-account for pulling the collector image from a private registries + # serviceAccount: otel-collector + config: + receivers: + nop: {} + otlp: + protocols: + grpc: + endpoint: 0.0.0.0:4317 + http: + endpoint: 0.0.0.0:4318 + # Scrape the collectors own metrics + prometheus: + config: + scrape_configs: + - job_name: opentelemetry-collector + scrape_interval: 10s + static_configs: + - targets: + - ${env:MY_POD_IP}:8888 + extensions: + health_check: + endpoint: ${env:MY_POD_IP}:13133 + # Use the API key from the env for authentication + bearertokenauth: + scheme: SUSEObservability + token: "${env:API_KEY}" + exporters: + nop: {} + otlp/suse-observability: + auth: + authenticator: bearertokenauth + # Put in your own otlp endpoint + endpoint: + compression: snappy + processors: + memory_limiter: + check_interval: 5s + limit_percentage: 80 + spike_limit_percentage: 25 + batch: {} + resource: + attributes: + - key: k8s.cluster.name + action: upsert + # Insert your own cluster name + value: + - key: service.instance.id + from_attribute: k8s.pod.uid + action: insert + # Use the k8s namespace also as the open telemetry namespace + - key: service.namespace + from_attribute: k8s.namespace.name + action: insert + connectors: + # Generate metrics for spans + spanmetrics: + metrics_expiration: 5m + namespace: otel_span + service: + extensions: [ health_check, bearertokenauth ] + pipelines: + traces: + receivers: [otlp] + processors: [memory_limiter, resource, batch] + exporters: [debug, spanmetrics, otlp/suse-observability] + metrics: + receivers: [otlp, spanmetrics, prometheus] + processors: [memory_limiter, resource, batch] + exporters: [debug, otlp/suse-observability] + logs: + receivers: [nop] + processors: [] + exporters: [nop] + telemetry: + metrics: + address: ${env:MY_POD_IP}:8888 +``` +{% endcode %} + +{% hint type="warning" %} +**Use the same cluster name as used for installing the SUSE Observability agent** if you also use the SUSE Observability agent with the Kubernetes stackpack. Using a different cluster name will result in an empty traces perspective for Kubernetes components and will overall make correlating information much harder for SUSE Observability and your users. +{% endhint %} + +Now apply this `collector.yaml` in the `open-telemetry` namespace to deploy a collector: + +```bash +kubectl apply --namespace open-telemetry --values collector.yaml +``` + +The collector offers a lot more configuration receivers, processors and exporters, for more details see our [collector page](../collector.md). For production usage often large amounts of spans are generated and you will want to start setting up [sampling](../sampling.md). + +## Auto-instrumentation + +### Configure auto-instrumentation + +Now we need to tell the operator how to configure the auto instrumentation for the different languages using another custom resource, of kind `Instrumentation`. It is mainly used to configure the collector that was just deployed as the telemetry endpoint for the instrumented applications. + +It can be defined in a single place and used by all pods in the cluster, but it is also possible to have a different `Instrumentation` in each namespace. We'll be doing the former here. Note that if you used a different namespace or a different name for the otel collector the endpoint in this file needs to be updated accordingly. + +Create an `instrumentation.yaml`: + +{% code title="otel-operator.yaml" lineNumbers="true" %} +```yaml +apiVersion: opentelemetry.io/v1alpha1 +kind: Instrumentation +metadata: + name: otel-instrumentation +spec: + exporter: + # default endpoint for the instrumentation + endpoint: http://otel-collector-collector.open-telemetry.svc.cluster.local:4317 + propagators: + - tracecontext + - baggage + defaults: + # To use the standard app.kubernetes.io/ labels for the service name, version and namespace: + useLabelsForResourceAttributes: true + python: + env: + # Python autoinstrumentation uses http/proto by default, so data must be sent to 4318 instead of 4317. + - name: OTEL_EXPORTER_OTLP_ENDPOINT + value: http://otel-collector-collector.open-telemetry.svc.cluster.local:4318 + dotnet: + env: + # Dotnet autoinstrumentation uses http/proto by default, so data must be sent to 4318 instead of 4317. + - name: OTEL_EXPORTER_OTLP_ENDPOINT + value: http://otel-collector-collector.open-telemetry.svc.cluster.local:4318 + go: + env: + # Go autoinstrumentation uses http/proto by default, so data must be sent to 4318 instead of 4317. + - name: OTEL_EXPORTER_OTLP_ENDPOINT + value: http://otel-collector-collector.open-telemetry.svc.cluster.local:4318 +``` +{% endcode %} + +Now apply the `instrumentation.yaml` also in the `open-telemetry` namespace: + +```bash +kubectl apply --namespace open-telemetry --values instrumentation.yaml +``` + +### Enable auto-instrumentation for a pod + +To instruct the operator to auto-instrument your applicaction pods we need to add an annotation to the pod: +* Java: `instrumentation.opentelemetry.io/inject-java: open-telemetry/otel-instrumentation` +* NodeJS: `instrumentation.opentelemetry.io/inject-nodejs: open-telemetry/otel-instrumentation` +* Python: `instrumentation.opentelemetry.io/inject-python: open-telemetry/otel-instrumentation` +* Go: `instrumentation.opentelemetry.io/inject-go: open-telemetry/otel-instrumentation` + +Note that the value of the annotation refers to the namespace and name of the `Instrumentation` resource that we created. Other options are: + +* "true" - inject and `Instrumentation` custom resource from the namespace. +* "my-instrumentation" - name of `Instrumentation` custom resource in the current namespace. +* "my-other-namespace/my-instrumentation" - namespace and name of `Instrumentation` custom resource in another namespace. +* "false" - do not inject + +When a pod with one of the annotations is created the operator modifies the pod via a mutation hook: +* It adds an init container that provides the auto-instrumentation library +* It modifies the first container of the pod to load the instrumentation during start up and it adds environment variables to configure the instrumentation + +If you need to customize which containers should be instrumented use the [operator documentation](https://github.com/open-telemetry/opentelemetry-operator?tab=readme-ov-file#multi-container-pods-with-multiple-instrumentations). + +{% hint type="warning" %} +Go auto-instrumentation requires elevated permissions. These permissions are set automatically by the operator: + +```yaml +securityContext: + privileged: true + runAsUser: 0 +``` +{% endhint %} + +## View the results +Go to SUSE Observability and make sure the Open Telemetry Stackpack is installed (via the main menu -> Stackpacks). + +After a short while and if your pods are getting some traffic you should be able to find them under their 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. + +If you also have the Kubernetes stackpack installed the instrumented pods will also have the traces available in the [trace perspective](/use/views/k8s-traces-perspective.md). + +## Next steps +You can add new charts to components, for example the service or service instance, for your application, by following [our guide](/use/metrics/k8s-add-charts.md). It is also possible to create [new monitors](/use/alerting/k8s-monitors.md) using the metrics and setup [notifications](/use/alerting/notifications/configure.md) to get notified when your application is not available or having performance issues. + +The operator, the `OpenTelemetryCollector`, and the `Instrumentation` custom resource, have more options that are documented in the [readme of the operator repository](https://github.com/open-telemetry/opentelemetry-operator). For example it is possible to install an optional [target allocator](https://github.com/open-telemetry/opentelemetry-operator?tab=readme-ov-file#target-allocator) via the `OpenTelemetryCollector` resource, it can be used to configure the Prometheus receiver of the collector. This is especially useful when you want to replace Prometheus operator and are using its `ServiceMonitor` and `PodMonitor` custom resources. + +# More info + +* [API keys](/use/security/k8s-ingestion-api-keys.md) +* [Open Telemetry API](../otlp-apis.md) +* [Customizing Open Telemetry Collector configuration](../collector.md) +* [Open Telemetry SDKs](../instrumentation/README.md) +* [Open Telemetry Operator](https://github.com/open-telemetry/opentelemetry-operator) \ No newline at end of file diff --git a/setup/otel/getting-started/getting-started-k8s.md b/setup/otel/getting-started/getting-started-k8s.md index 013635ceb..989736f85 100644 --- a/setup/otel/getting-started/getting-started-k8s.md +++ b/setup/otel/getting-started/getting-started-k8s.md @@ -2,7 +2,7 @@ description: SUSE Observability --- -# Getting Started with Open Telemetry on Rancher / Kubernetes +# Getting Started with Open Telemetry on Kubernetes Here is the setup we'll be creating, for an application that needs to be monitored: @@ -10,7 +10,7 @@ Here is the setup we'll be creating, for an application that needs to be monitor * The Open Telemetry collector running near the observed application(s), so in cluster A, and sending the data to SUSE Observability * SUSE Observability running in cluster B, or SUSE Cloud Observability -![Container instrumentation with Opentelemetry via collector running as Kubernetes deployment](/.gitbook/assets/otel/open-telemetry-collector-kubernetes.png) +![Container instrumentation with Open Telemetry via collector running as Kubernetes deployment](/.gitbook/assets/otel/open-telemetry-collector-kubernetes.png) ## The Open Telemetry collector diff --git a/setup/otel/getting-started/getting-started-lambda.md b/setup/otel/getting-started/getting-started-lambda.md index 509877e7c..625a0a0f5 100644 --- a/setup/otel/getting-started/getting-started-lambda.md +++ b/setup/otel/getting-started/getting-started-lambda.md @@ -9,7 +9,7 @@ We'll setup monitoring for one or more AWS Lambda functions: * The Open Telemetry collector * SUSE Observability or SUSE Cloud Observability -![AWS Lambda Instrumentation With Opentelemetry with Open Telemetry collector running in Kubernetes](/.gitbook/assets/otel/open-telemetry-collector-lambda.png) +![AWS Lambda Instrumentation With Open Telemetry with Open Telemetry collector running in Kubernetes](/.gitbook/assets/otel/open-telemetry-collector-lambda.png) ## The Open Telemetry collector From 626154a31ade2e1950f8915470a350d03e971efc Mon Sep 17 00:00:00 2001 From: Remco Beckers Date: Fri, 18 Apr 2025 16:55:43 +0200 Subject: [PATCH 2/5] Fix syntax mistake --- setup/otel/collector.md | 2 +- setup/otel/getting-started/getting-started-k8s-operator.md | 4 ++-- setup/otel/getting-started/getting-started-k8s.md | 4 ++-- setup/otel/getting-started/getting-started-lambda.md | 2 +- setup/otel/getting-started/getting-started-linux.md | 2 +- setup/otel/instrumentation/sdk-exporter-config.md | 2 +- 6 files changed, 8 insertions(+), 8 deletions(-) diff --git a/setup/otel/collector.md b/setup/otel/collector.md index d436187ba..97a7b80e8 100644 --- a/setup/otel/collector.md +++ b/setup/otel/collector.md @@ -81,7 +81,7 @@ exporters: compression: snappy ``` -{% hint type="warning" %} +{% hint style="warning" %} The OTLP HTTP endpoint for SUSE Observability is different from the OTLP endpoint. Use the [OTLP APIs](./otlp-apis.md) to find the correct URL. {% endhint %} diff --git a/setup/otel/getting-started/getting-started-k8s-operator.md b/setup/otel/getting-started/getting-started-k8s-operator.md index 69f8abeb6..e5274ebfa 100644 --- a/setup/otel/getting-started/getting-started-k8s-operator.md +++ b/setup/otel/getting-started/getting-started-k8s-operator.md @@ -193,7 +193,7 @@ spec: ``` {% endcode %} -{% hint type="warning" %} +{% hint style="warning" %} **Use the same cluster name as used for installing the SUSE Observability agent** if you also use the SUSE Observability agent with the Kubernetes stackpack. Using a different cluster name will result in an empty traces perspective for Kubernetes components and will overall make correlating information much harder for SUSE Observability and your users. {% endhint %} @@ -276,7 +276,7 @@ When a pod with one of the annotations is created the operator modifies the pod If you need to customize which containers should be instrumented use the [operator documentation](https://github.com/open-telemetry/opentelemetry-operator?tab=readme-ov-file#multi-container-pods-with-multiple-instrumentations). -{% hint type="warning" %} +{% hint style="warning" %} Go auto-instrumentation requires elevated permissions. These permissions are set automatically by the operator: ```yaml diff --git a/setup/otel/getting-started/getting-started-k8s.md b/setup/otel/getting-started/getting-started-k8s.md index 989736f85..9220cc7f0 100644 --- a/setup/otel/getting-started/getting-started-k8s.md +++ b/setup/otel/getting-started/getting-started-k8s.md @@ -15,7 +15,7 @@ Here is the setup we'll be creating, for an application that needs to be monitor ## The Open Telemetry collector -{% hint type="info" %} +{% hint style="info" %} 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. {% endhint %} @@ -131,7 +131,7 @@ config: ``` {% endcode %} -{% hint type="warning" %} +{% hint style="warning" %} **Use the same cluster name as used for installing the SUSE Observability agent** if you also use the SUSE Observability agent with the Kubernetes stackpack. Using a different cluster name will result in an empty traces perspective for Kubernetes components and will overall make correlating information much harder for SUSE Observability and your users. {% endhint %} diff --git a/setup/otel/getting-started/getting-started-lambda.md b/setup/otel/getting-started/getting-started-lambda.md index 625a0a0f5..b67e2f639 100644 --- a/setup/otel/getting-started/getting-started-lambda.md +++ b/setup/otel/getting-started/getting-started-lambda.md @@ -13,7 +13,7 @@ We'll setup monitoring for one or more AWS Lambda functions: ## The Open Telemetry collector -{% hint type="info" %} +{% hint style="info" %} 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. {% endhint %} diff --git a/setup/otel/getting-started/getting-started-linux.md b/setup/otel/getting-started/getting-started-linux.md index a10d5beed..a97d3e829 100644 --- a/setup/otel/getting-started/getting-started-linux.md +++ b/setup/otel/getting-started/getting-started-linux.md @@ -14,7 +14,7 @@ Here is the setup we'll be creating, for an application that needs to be monitor ## Install the Open Telemetry collector -{% hint type="info" %} +{% hint style="info" %} 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. {% endhint %} diff --git a/setup/otel/instrumentation/sdk-exporter-config.md b/setup/otel/instrumentation/sdk-exporter-config.md index 83f9fa219..c7769ca9c 100644 --- a/setup/otel/instrumentation/sdk-exporter-config.md +++ b/setup/otel/instrumentation/sdk-exporter-config.md @@ -81,6 +81,6 @@ In small test setups it can be convenient to directly send data from your instru * For gRPC use the OTLP endpoint for SUSE Observability, see the [OTLP APIs page](../otlp-apis.md). * For HTTP use the OTLP over HTTP endpoint for SUSE Observability, see the [OTLP APIs page](../otlp-apis.md). -{% hint type="info" %} +{% hint style="info" %} Replace both the collector URL **and** the port with the SUSE Observability endpoints. Depending on your SUSE Observability installation the ports will be different. {% endhint %} From a4762299fc3c7b94dad8402f771ac8e3030e4e0b Mon Sep 17 00:00:00 2001 From: Remco Beckers Date: Fri, 18 Apr 2025 17:47:43 +0200 Subject: [PATCH 3/5] Update after testing docs --- .../getting-started-k8s-operator.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/setup/otel/getting-started/getting-started-k8s-operator.md b/setup/otel/getting-started/getting-started-k8s-operator.md index e5274ebfa..493e8b5a0 100644 --- a/setup/otel/getting-started/getting-started-k8s-operator.md +++ b/setup/otel/getting-started/getting-started-k8s-operator.md @@ -50,9 +50,8 @@ manager: repository: ghcr.io/open-telemetry/opentelemetry-operator/opentelemetry-operator collectorImage: # find the latest collector releases at https://github.com/open-telemetry/opentelemetry-collector-releases/releases - repository: - ghcr.io/open-telemetry/opentelemetry-collector-k8s - tag: 0.123.1 + repository: otel/opentelemetry-collector-k8s + tag: 0.123.0 targetAllocatorImage: repository: "" tag: "" @@ -117,7 +116,6 @@ spec: # serviceAccount: otel-collector config: receivers: - nop: {} otlp: protocols: grpc: @@ -141,6 +139,7 @@ spec: scheme: SUSEObservability token: "${env:API_KEY}" exporters: + debug: {} nop: {} otlp/suse-observability: auth: @@ -184,7 +183,7 @@ spec: processors: [memory_limiter, resource, batch] exporters: [debug, otlp/suse-observability] logs: - receivers: [nop] + receivers: [otlp] processors: [] exporters: [nop] telemetry: @@ -200,7 +199,7 @@ spec: Now apply this `collector.yaml` in the `open-telemetry` namespace to deploy a collector: ```bash -kubectl apply --namespace open-telemetry --values collector.yaml +kubectl apply --namespace open-telemetry -f collector.yaml ``` The collector offers a lot more configuration receivers, processors and exporters, for more details see our [collector page](../collector.md). For production usage often large amounts of spans are generated and you will want to start setting up [sampling](../sampling.md). @@ -215,7 +214,7 @@ It can be defined in a single place and used by all pods in the cluster, but it Create an `instrumentation.yaml`: -{% code title="otel-operator.yaml" lineNumbers="true" %} +{% code title="instrumentation.yaml" lineNumbers="true" %} ```yaml apiVersion: opentelemetry.io/v1alpha1 kind: Instrumentation @@ -252,7 +251,7 @@ spec: Now apply the `instrumentation.yaml` also in the `open-telemetry` namespace: ```bash -kubectl apply --namespace open-telemetry --values instrumentation.yaml +kubectl apply --namespace open-telemetry -f instrumentation.yaml ``` ### Enable auto-instrumentation for a pod From ce64764d017c0de29dca6f1f2e669d361f5d8f80 Mon Sep 17 00:00:00 2001 From: Remco Beckers Date: Fri, 2 May 2025 17:16:38 +0200 Subject: [PATCH 4/5] Clarify that port is required --- setup/otel/getting-started/getting-started-k8s-operator.md | 6 +++--- setup/otel/getting-started/getting-started-k8s.md | 6 +++--- setup/otel/getting-started/getting-started-lambda.md | 6 +++--- setup/otel/getting-started/getting-started-linux.md | 6 +++--- setup/otel/otlp-apis.md | 4 ++-- 5 files changed, 14 insertions(+), 14 deletions(-) diff --git a/setup/otel/getting-started/getting-started-k8s-operator.md b/setup/otel/getting-started/getting-started-k8s-operator.md index 493e8b5a0..4e9beb972 100644 --- a/setup/otel/getting-started/getting-started-k8s-operator.md +++ b/setup/otel/getting-started/getting-started-k8s-operator.md @@ -99,7 +99,7 @@ This only installs the operator. Continue to install the collector and enable au The operator manages one or more collector deployments via a Kubernetes custom resource of kind `OpenTelemetryCollector`. We'll create one using the same configuration as used in the [Kubernetes getting started guide](./getting-started-k8s.md). -It uses the secret created earlier in the guide. Make sure to replace `` with your OTLP endpoint (see [OTLP API](../otlp-apis.md) for your endpoint) and insert the name for your Kubernetes cluster instead of ``: +It uses the secret created earlier in the guide. Make sure to replace `` with your OTLP endpoint (see [OTLP API](../otlp-apis.md) for your endpoint) and insert the name for your Kubernetes cluster instead of ``: {% code title="collector.yaml" lineNumbers="true" %} ```yaml @@ -144,8 +144,8 @@ spec: otlp/suse-observability: auth: authenticator: bearertokenauth - # Put in your own otlp endpoint - endpoint: + # Put in your own otlp endpoint, for example suse-observability.my.company.com:443 + endpoint: compression: snappy processors: memory_limiter: diff --git a/setup/otel/getting-started/getting-started-k8s.md b/setup/otel/getting-started/getting-started-k8s.md index 9220cc7f0..ae08bdff9 100644 --- a/setup/otel/getting-started/getting-started-k8s.md +++ b/setup/otel/getting-started/getting-started-k8s.md @@ -47,7 +47,7 @@ We install the collector with a Helm chart provided by the Open Telemetry projec helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts ``` -Create a `otel-collector.yaml` values file for the Helm chart. Here is a good starting point for usage with SUSE Observability, replace `` with your OTLP endpoint (see [OTLP API](../otlp-apis.md) for your endpoint) and insert the name for your Kubernetes cluster instead of ``: +Create a `otel-collector.yaml` values file for the Helm chart. Here is a good starting point for usage with SUSE Observability, replace `` with your OTLP endpoint (see [OTLP API](../otlp-apis.md) for your endpoint) and insert the name for your Kubernetes cluster instead of ``: {% code title="otel-collector.yaml" lineNumbers="true" %} ```yaml @@ -86,8 +86,8 @@ config: otlp/suse-observability: auth: authenticator: bearertokenauth - # Put in your own otlp endpoint - endpoint: + # Put in your own otlp endpoint, for example suse-observability.my.company.com:443 + endpoint: compression: snappy processors: memory_limiter: diff --git a/setup/otel/getting-started/getting-started-lambda.md b/setup/otel/getting-started/getting-started-lambda.md index b67e2f639..7cc1f7fe2 100644 --- a/setup/otel/getting-started/getting-started-lambda.md +++ b/setup/otel/getting-started/getting-started-lambda.md @@ -38,7 +38,7 @@ We install the collector with a Helm chart provided by the Open Telemetry projec helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts ``` -Create a `otel-collector.yaml` values file for the Helm chart. Here is a good starting point for usage with SUSE Observability, replace `` with your OTLP endpoint (see [OTLP API](../otlp-apis.md) for your endpoint) and insert the name for your Kubernetes cluster instead of ``. When using the ingress configuration also make sure to insert your own domain name and the corresponding TLS certificate secret in the marked locations. +Create a `otel-collector.yaml` values file for the Helm chart. Here is a good starting point for usage with SUSE Observability, replace `` with your OTLP endpoint (see [OTLP API](../otlp-apis.md) for your endpoint) and insert the name for your Kubernetes cluster instead of ``. When using the ingress configuration also make sure to insert your own domain name and the corresponding TLS certificate secret in the marked locations. {% code title="otel-collector.yaml" lineNumbers="true" %} ```yaml @@ -72,8 +72,8 @@ config: otlp: auth: authenticator: bearertokenauth - # Put in your own otlp endpoint - endpoint: + # Put in your own otlp endpoint, for example suse-observability.my.company.com:443 + endpoint: service: extensions: [health_check, bearertokenauth] diff --git a/setup/otel/getting-started/getting-started-linux.md b/setup/otel/getting-started/getting-started-linux.md index a97d3e829..8d3577985 100644 --- a/setup/otel/getting-started/getting-started-linux.md +++ b/setup/otel/getting-started/getting-started-linux.md @@ -62,7 +62,7 @@ sudo rpm -iv1 otelcol-contrib_0.123.1_linux_arm64.rpm For other installation options use the [Open Telemetry instructions](https://opentelemetry.io/docs/collector/installation/#linux). -After installation modify the collector configuration by editing `/etc/otelcol-contrib/config.yaml`. Change the file such that it looks like the `config.yaml` example here, replace `` with your OTLP endpoint (see [OTLP API](../otlp-apis.md) for your endpoint) and insert your receiver api key for `` (see [here](/use/security/k8s-ingestion-api-keys.md#api-keys) where to find it): +After installation modify the collector configuration by editing `/etc/otelcol-contrib/config.yaml`. Change the file such that it looks like the `config.yaml` example here, replace `` with your OTLP endpoint (see [OTLP API](../otlp-apis.md) for your endpoint) and insert your receiver api key for `` (see [here](/use/security/k8s-ingestion-api-keys.md#api-keys) where to find it): {% code title="config.yaml" lineNumbers="true" %} ```yaml @@ -99,8 +99,8 @@ exporters: compression: snappy auth: authenticator: bearertokenauth - # Put in your own otlp endpoint - endpoint: + # Put in your own otlp endpoint, for example suse-observability.my.company.com:443 + endpoint: processors: memory_limiter: check_interval: 5s diff --git a/setup/otel/otlp-apis.md b/setup/otel/otlp-apis.md index b460acb37..2a370c3ed 100644 --- a/setup/otel/otlp-apis.md +++ b/setup/otel/otlp-apis.md @@ -10,8 +10,8 @@ SUSE Observability supports 2 versions of the OTLP protocol, the `grpc` version The endpoints for SUSE Cloud Observability are: -* OTLP: `https://otlp-.app.stackstate`.com:443 -* OTLP over HTTP: `https://otlp-http-`.app.stackstate.com +* OTLP: `https://otlp-.app.stackstate.com:443` +* OTLP over HTTP: `https://otlp-http-.app.stackstate.com` ## Self-hosted SUSE Observability From 6ef28783c75edf3770eefd7168032f49ad531e3c Mon Sep 17 00:00:00 2001 From: Remco Beckers Date: Tue, 6 May 2025 09:06:58 +0200 Subject: [PATCH 5/5] Fix cloud url --- setup/otel/otlp-apis.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/setup/otel/otlp-apis.md b/setup/otel/otlp-apis.md index 2a370c3ed..1fb6d96d2 100644 --- a/setup/otel/otlp-apis.md +++ b/setup/otel/otlp-apis.md @@ -10,8 +10,8 @@ SUSE Observability supports 2 versions of the OTLP protocol, the `grpc` version The endpoints for SUSE Cloud Observability are: -* OTLP: `https://otlp-.app.stackstate.com:443` -* OTLP over HTTP: `https://otlp-http-.app.stackstate.com` +* OTLP: `https://otlp-.app.stackstate.io:443` +* OTLP over HTTP: `https://otlp-http-.app.stackstate.io` ## Self-hosted SUSE Observability