DevFW-CICD/ingress-nginx-helm
14
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Docs: Convert opentelemetry.md from CRLF to LF. (#12006)

Browse source
This commit is contained in:
Marco Ebert 2024-09-23 10:46:34 +02:00 committed by GitHub
parent 85ccb34282
commit 6495d9f0d1
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 314 additions and 314 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

628
docs/user-guide/third-party-addons/opentelemetry.md
View file

@ -1,314 +1,314 @@
# OpenTelemetry # OpenTelemetry
Enables requests served by NGINX for distributed telemetry via The OpenTelemetry Project. Enables requests served by NGINX for distributed telemetry via The OpenTelemetry Project.
Using the third party module [opentelemetry-cpp-contrib/nginx](https://github.com/open-telemetry/opentelemetry-cpp-contrib/tree/main/instrumentation/nginx) the Ingress-Nginx Controller can configure NGINX to enable [OpenTelemetry](http://opentelemetry.io) instrumentation. Using the third party module [opentelemetry-cpp-contrib/nginx](https://github.com/open-telemetry/opentelemetry-cpp-contrib/tree/main/instrumentation/nginx) the Ingress-Nginx Controller can configure NGINX to enable [OpenTelemetry](http://opentelemetry.io) instrumentation.
By default this feature is disabled. By default this feature is disabled.
Check out this demo showcasing OpenTelemetry in Ingress NGINX. The video provides an overview and Check out this demo showcasing OpenTelemetry in Ingress NGINX. The video provides an overview and
practical demonstration of how OpenTelemetry can be utilized in Ingress NGINX for observability practical demonstration of how OpenTelemetry can be utilized in Ingress NGINX for observability
and monitoring purposes. and monitoring purposes.
<p align="center"> <p align="center">
<a href="https://www.youtube.com/watch?v=jpBfgJpTcfw&t=129" target="_blank" rel="noopener noreferrer"> <a href="https://www.youtube.com/watch?v=jpBfgJpTcfw&t=129" target="_blank" rel="noopener noreferrer">
<img src="https://img.youtube.com/vi/jpBfgJpTcfw/0.jpg" alt="Video Thumbnail" /> <img src="https://img.youtube.com/vi/jpBfgJpTcfw/0.jpg" alt="Video Thumbnail" />
</a> </a>
</p> </p>
<p align="center">Demo: OpenTelemetry in Ingress NGINX.</p> <p align="center">Demo: OpenTelemetry in Ingress NGINX.</p>
## Usage ## Usage
To enable the instrumentation we must enable OpenTelemetry in the configuration ConfigMap: To enable the instrumentation we must enable OpenTelemetry in the configuration ConfigMap:
```yaml ```yaml
data: data:
enable-opentelemetry: "true" enable-opentelemetry: "true"
``` ```
To enable or disable instrumentation for a single Ingress, use To enable or disable instrumentation for a single Ingress, use
the `enable-opentelemetry` annotation: the `enable-opentelemetry` annotation:
```yaml ```yaml
kind: Ingress kind: Ingress
metadata: metadata:
annotations: annotations:
nginx.ingress.kubernetes.io/enable-opentelemetry: "true" nginx.ingress.kubernetes.io/enable-opentelemetry: "true"
``` ```
We must also set the host to use when uploading traces: We must also set the host to use when uploading traces:
```yaml ```yaml
otlp-collector-host: "otel-coll-collector.otel.svc" otlp-collector-host: "otel-coll-collector.otel.svc"
``` ```
NOTE: While the option is called `otlp-collector-host`, you will need to point this to any backend that receives otlp-grpc. NOTE: While the option is called `otlp-collector-host`, you will need to point this to any backend that receives otlp-grpc.
Next you will need to deploy a distributed telemetry system which uses OpenTelemetry. Next you will need to deploy a distributed telemetry system which uses OpenTelemetry.
[opentelemetry-collector](https://github.com/open-telemetry/opentelemetry-collector), [Jaeger](https://www.jaegertracing.io/) [opentelemetry-collector](https://github.com/open-telemetry/opentelemetry-collector), [Jaeger](https://www.jaegertracing.io/)
[Tempo](https://github.com/grafana/tempo), and [zipkin](https://zipkin.io/) [Tempo](https://github.com/grafana/tempo), and [zipkin](https://zipkin.io/)
have been tested. have been tested.
Other optional configuration options: Other optional configuration options:
```yaml ```yaml
# specifies the name to use for the server span # specifies the name to use for the server span
opentelemetry-operation-name opentelemetry-operation-name
# sets whether or not to trust incoming telemetry spans # sets whether or not to trust incoming telemetry spans
opentelemetry-trust-incoming-span opentelemetry-trust-incoming-span
# specifies the port to use when uploading traces, Default: 4317 # specifies the port to use when uploading traces, Default: 4317
otlp-collector-port otlp-collector-port
# specifies the service name to use for any traces created, Default: nginx # specifies the service name to use for any traces created, Default: nginx
otel-service-name otel-service-name
# The maximum queue size. After the size is reached data are dropped. # The maximum queue size. After the size is reached data are dropped.
otel-max-queuesize otel-max-queuesize
# The delay interval in milliseconds between two consecutive exports. # The delay interval in milliseconds between two consecutive exports.
otel-schedule-delay-millis otel-schedule-delay-millis
# How long the export can run before it is cancelled. # How long the export can run before it is cancelled.
otel-schedule-delay-millis otel-schedule-delay-millis
# The maximum batch size of every export. It must be smaller or equal to maxQueueSize. # The maximum batch size of every export. It must be smaller or equal to maxQueueSize.
otel-max-export-batch-size otel-max-export-batch-size
# specifies sample rate for any traces created, Default: 0.01 # specifies sample rate for any traces created, Default: 0.01
otel-sampler-ratio otel-sampler-ratio
# specifies the sampler to be used when sampling traces. # specifies the sampler to be used when sampling traces.
# The available samplers are: AlwaysOn, AlwaysOff, TraceIdRatioBased, Default: AlwaysOff # The available samplers are: AlwaysOn, AlwaysOff, TraceIdRatioBased, Default: AlwaysOff
otel-sampler otel-sampler
# Uses sampler implementation which by default will take a sample if parent Activity is sampled, Default: false # Uses sampler implementation which by default will take a sample if parent Activity is sampled, Default: false
otel-sampler-parent-based otel-sampler-parent-based
``` ```
Note that you can also set whether to trust incoming spans (global default is true) per-location using annotations like the following: Note that you can also set whether to trust incoming spans (global default is true) per-location using annotations like the following:
```yaml ```yaml
kind: Ingress kind: Ingress
metadata: metadata:
annotations: annotations:
nginx.ingress.kubernetes.io/opentelemetry-trust-incoming-span: "true" nginx.ingress.kubernetes.io/opentelemetry-trust-incoming-span: "true"
``` ```
## Examples ## Examples
The following examples show how to deploy and test different distributed telemetry systems. These example can be performed using Docker Desktop. The following examples show how to deploy and test different distributed telemetry systems. These example can be performed using Docker Desktop.
In the [esigo/nginx-example](https://github.com/esigo/nginx-example) In the [esigo/nginx-example](https://github.com/esigo/nginx-example)
GitHub repository is an example of a simple hello service: GitHub repository is an example of a simple hello service:
```mermaid ```mermaid
graph TB graph TB
subgraph Browser subgraph Browser
start["http://esigo.dev/hello/nginx"] start["http://esigo.dev/hello/nginx"]
end end
subgraph app subgraph app
sa[service-a] sa[service-a]
sb[service-b] sb[service-b]
sa --> |name: nginx| sb sa --> |name: nginx| sb
sb --> |hello nginx!| sa sb --> |hello nginx!| sa
end end
subgraph otel subgraph otel
otc["Otel Collector"] otc["Otel Collector"]
end end
subgraph observability subgraph observability
tempo["Tempo"] tempo["Tempo"]
grafana["Grafana"] grafana["Grafana"]
backend["Jaeger"] backend["Jaeger"]
zipkin["Zipkin"] zipkin["Zipkin"]
end end
subgraph ingress-nginx subgraph ingress-nginx
ngx[nginx] ngx[nginx]
end end
subgraph ngx[nginx] subgraph ngx[nginx]
ng[nginx] ng[nginx]
om[OpenTelemetry module] om[OpenTelemetry module]
end end
subgraph Node subgraph Node
app app
otel otel
observability observability
ingress-nginx ingress-nginx
om --> |otlp-gRPC| otc --> |jaeger| backend om --> |otlp-gRPC| otc --> |jaeger| backend
otc --> |zipkin| zipkin otc --> |zipkin| zipkin
otc --> |otlp-gRPC| tempo --> grafana otc --> |otlp-gRPC| tempo --> grafana
sa --> |otlp-gRPC| otc sa --> |otlp-gRPC| otc
sb --> |otlp-gRPC| otc sb --> |otlp-gRPC| otc
start --> ng --> sa start --> ng --> sa
end end
``` ```
To install the example and collectors run: To install the example and collectors run:
1. Enable Ingress addon with: 1. Enable Ingress addon with:
```yaml ```yaml
opentelemetry: opentelemetry:
enabled: true enabled: true
image: registry.k8s.io/ingress-nginx/opentelemetry-1.25.3:v20240813-b933310d@sha256:f7604ac0547ed64d79b98d92133234e66c2c8aade3c1f4809fed5eec1fb7f922 image: registry.k8s.io/ingress-nginx/opentelemetry-1.25.3:v20240813-b933310d@sha256:f7604ac0547ed64d79b98d92133234e66c2c8aade3c1f4809fed5eec1fb7f922
containerSecurityContext: containerSecurityContext:
allowPrivilegeEscalation: false allowPrivilegeEscalation: false
``` ```
2. Enable OpenTelemetry and set the otlp-collector-host: 2. Enable OpenTelemetry and set the otlp-collector-host:
```yaml ```yaml
$ echo ' $ echo '
apiVersion: v1 apiVersion: v1
kind: ConfigMap kind: ConfigMap
data: data:
enable-opentelemetry: "true" enable-opentelemetry: "true"
opentelemetry-config: "/etc/nginx/opentelemetry.toml" opentelemetry-config: "/etc/nginx/opentelemetry.toml"
opentelemetry-operation-name: "HTTP $request_method $service_name $uri" opentelemetry-operation-name: "HTTP $request_method $service_name $uri"
opentelemetry-trust-incoming-span: "true" opentelemetry-trust-incoming-span: "true"
otlp-collector-host: "otel-coll-collector.otel.svc" otlp-collector-host: "otel-coll-collector.otel.svc"
otlp-collector-port: "4317" otlp-collector-port: "4317"
otel-max-queuesize: "2048" otel-max-queuesize: "2048"
otel-schedule-delay-millis: "5000" otel-schedule-delay-millis: "5000"
otel-max-export-batch-size: "512" otel-max-export-batch-size: "512"
otel-service-name: "nginx-proxy" # Opentelemetry resource name otel-service-name: "nginx-proxy" # Opentelemetry resource name
otel-sampler: "AlwaysOn" # Also: AlwaysOff, TraceIdRatioBased otel-sampler: "AlwaysOn" # Also: AlwaysOff, TraceIdRatioBased
otel-sampler-ratio: "1.0" otel-sampler-ratio: "1.0"
otel-sampler-parent-based: "false" otel-sampler-parent-based: "false"
metadata: metadata:
name: ingress-nginx-controller name: ingress-nginx-controller
namespace: ingress-nginx namespace: ingress-nginx
' | kubectl replace -f - ' | kubectl replace -f -
``` ```
4. Deploy otel-collector, grafana and Jaeger backend: 4. Deploy otel-collector, grafana and Jaeger backend:
```bash ```bash
# add helm charts needed for grafana and OpenTelemetry collector # add helm charts needed for grafana and OpenTelemetry collector
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm repo add grafana https://grafana.github.io/helm-charts helm repo add grafana https://grafana.github.io/helm-charts
helm repo update helm repo update
# deploy cert-manager needed for OpenTelemetry collector operator # deploy cert-manager needed for OpenTelemetry collector operator
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.9.1/cert-manager.yaml kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.9.1/cert-manager.yaml
# create observability namespace # create observability namespace
kubectl apply -f https://raw.githubusercontent.com/esigo/nginx-example/main/observability/namespace.yaml kubectl apply -f https://raw.githubusercontent.com/esigo/nginx-example/main/observability/namespace.yaml
# install OpenTelemetry collector operator # install OpenTelemetry collector operator
helm upgrade --install otel-collector-operator -n otel --create-namespace open-telemetry/opentelemetry-operator helm upgrade --install otel-collector-operator -n otel --create-namespace open-telemetry/opentelemetry-operator
# deploy OpenTelemetry collector # deploy OpenTelemetry collector
kubectl apply -f https://raw.githubusercontent.com/esigo/nginx-example/main/observability/collector.yaml kubectl apply -f https://raw.githubusercontent.com/esigo/nginx-example/main/observability/collector.yaml
# deploy Jaeger all-in-one # deploy Jaeger all-in-one
kubectl apply -f https://github.com/jaegertracing/jaeger-operator/releases/download/v1.37.0/jaeger-operator.yaml -n observability kubectl apply -f https://github.com/jaegertracing/jaeger-operator/releases/download/v1.37.0/jaeger-operator.yaml -n observability
kubectl apply -f https://raw.githubusercontent.com/esigo/nginx-example/main/observability/jaeger.yaml -n observability kubectl apply -f https://raw.githubusercontent.com/esigo/nginx-example/main/observability/jaeger.yaml -n observability
# deploy zipkin # deploy zipkin
kubectl apply -f https://raw.githubusercontent.com/esigo/nginx-example/main/observability/zipkin.yaml -n observability kubectl apply -f https://raw.githubusercontent.com/esigo/nginx-example/main/observability/zipkin.yaml -n observability
# deploy tempo and grafana # deploy tempo and grafana
helm upgrade --install tempo grafana/tempo --create-namespace -n observability helm upgrade --install tempo grafana/tempo --create-namespace -n observability
helm upgrade -f https://raw.githubusercontent.com/esigo/nginx-example/main/observability/grafana/grafana-values.yaml --install grafana grafana/grafana --create-namespace -n observability helm upgrade -f https://raw.githubusercontent.com/esigo/nginx-example/main/observability/grafana/grafana-values.yaml --install grafana grafana/grafana --create-namespace -n observability
``` ```
3. Build and deploy demo app: 3. Build and deploy demo app:
```bash ```bash
# build images # build images
make images make images
# deploy demo app: # deploy demo app:
make deploy-app make deploy-app
``` ```
5. Make a few requests to the Service: 5. Make a few requests to the Service:
```bash ```bash
kubectl port-forward --namespace=ingress-nginx service/ingress-nginx-controller 8090:80 kubectl port-forward --namespace=ingress-nginx service/ingress-nginx-controller 8090:80
curl http://esigo.dev:8090/hello/nginx curl http://esigo.dev:8090/hello/nginx
StatusCode : 200 StatusCode : 200
StatusDescription : OK StatusDescription : OK
Content : {"v":"hello nginx!"} Content : {"v":"hello nginx!"}
RawContent : HTTP/1.1 200 OK RawContent : HTTP/1.1 200 OK
Connection: keep-alive Connection: keep-alive
Content-Length: 21 Content-Length: 21
Content-Type: text/plain; charset=utf-8 Content-Type: text/plain; charset=utf-8
Date: Mon, 10 Oct 2022 17:43:33 GMT Date: Mon, 10 Oct 2022 17:43:33 GMT
{"v":"hello nginx!"} {"v":"hello nginx!"}
Forms : {} Forms : {}
Headers : {[Connection, keep-alive], [Content-Length, 21], [Content-Type, text/plain; charset=utf-8], [Date, Headers : {[Connection, keep-alive], [Content-Length, 21], [Content-Type, text/plain; charset=utf-8], [Date,
Mon, 10 Oct 2022 17:43:33 GMT]} Mon, 10 Oct 2022 17:43:33 GMT]}
Images : {} Images : {}
InputFields : {} InputFields : {}
Links : {} Links : {}
ParsedHtml : System.__ComObject ParsedHtml : System.__ComObject
RawContentLength : 21 RawContentLength : 21
``` ```
6. View the Grafana UI: 6. View the Grafana UI:
```bash ```bash
kubectl port-forward --namespace=observability service/grafana 3000:80 kubectl port-forward --namespace=observability service/grafana 3000:80
``` ```
In the Grafana interface we can see the details: In the Grafana interface we can see the details:
![grafana screenshot](../../images/otel-grafana-demo.png "grafana screenshot") ![grafana screenshot](../../images/otel-grafana-demo.png "grafana screenshot")
7. View the Jaeger UI: 7. View the Jaeger UI:
```bash ```bash
kubectl port-forward --namespace=observability service/jaeger-all-in-one-query 16686:16686 kubectl port-forward --namespace=observability service/jaeger-all-in-one-query 16686:16686
``` ```
In the Jaeger interface we can see the details: In the Jaeger interface we can see the details:
![Jaeger screenshot](../../images/otel-jaeger-demo.png "Jaeger screenshot") ![Jaeger screenshot](../../images/otel-jaeger-demo.png "Jaeger screenshot")
8. View the Zipkin UI: 8. View the Zipkin UI:
```bash ```bash
kubectl port-forward --namespace=observability service/zipkin 9411:9411 kubectl port-forward --namespace=observability service/zipkin 9411:9411
``` ```
In the Zipkin interface we can see the details: In the Zipkin interface we can see the details:
![zipkin screenshot](../../images/otel-zipkin-demo.png "zipkin screenshot") ![zipkin screenshot](../../images/otel-zipkin-demo.png "zipkin screenshot")
## Migration from OpenTracing, Jaeger, Zipkin and Datadog ## Migration from OpenTracing, Jaeger, Zipkin and Datadog
If you are migrating from OpenTracing, Jaeger, Zipkin, or Datadog to OpenTelemetry, If you are migrating from OpenTracing, Jaeger, Zipkin, or Datadog to OpenTelemetry,
you may need to update various annotations and configurations. Here are the mappings you may need to update various annotations and configurations. Here are the mappings
for common annotations and configurations: for common annotations and configurations:
### Annotations ### Annotations
| Legacy | OpenTelemetry | | Legacy | OpenTelemetry |
|---------------------------------------------------------------|-----------------------------------------------------------------| |---------------------------------------------------------------|-----------------------------------------------------------------|
| `nginx.ingress.kubernetes.io/enable-opentracing` | `nginx.ingress.kubernetes.io/enable-opentelemetry` | | `nginx.ingress.kubernetes.io/enable-opentracing` | `nginx.ingress.kubernetes.io/enable-opentelemetry` |
| `nginx.ingress.kubernetes.io/opentracing-trust-incoming-span` | `nginx.ingress.kubernetes.io/opentelemetry-trust-incoming-span` | | `nginx.ingress.kubernetes.io/opentracing-trust-incoming-span` | `nginx.ingress.kubernetes.io/opentelemetry-trust-incoming-span` |
### Configs ### Configs
| Legacy | OpenTelemetry | | Legacy | OpenTelemetry |
|---------------------------------------|----------------------------------------------| |---------------------------------------|----------------------------------------------|
| `opentracing-operation-name` | `opentelemetry-operation-name` | | `opentracing-operation-name` | `opentelemetry-operation-name` |
| `opentracing-location-operation-name` | `opentelemetry-operation-name` | | `opentracing-location-operation-name` | `opentelemetry-operation-name` |
| `opentracing-trust-incoming-span` | `opentelemetry-trust-incoming-span` | | `opentracing-trust-incoming-span` | `opentelemetry-trust-incoming-span` |
| `zipkin-collector-port` | `otlp-collector-port` | | `zipkin-collector-port` | `otlp-collector-port` |
| `zipkin-service-name` | `otel-service-name` | | `zipkin-service-name` | `otel-service-name` |
| `zipkin-sample-rate` | `otel-sampler-ratio` | | `zipkin-sample-rate` | `otel-sampler-ratio` |
| `jaeger-collector-port` | `otlp-collector-port` | | `jaeger-collector-port` | `otlp-collector-port` |
| `jaeger-endpoint` | `otlp-collector-port`, `otlp-collector-host` | | `jaeger-endpoint` | `otlp-collector-port`, `otlp-collector-host` |
| `jaeger-service-name` | `otel-service-name` | | `jaeger-service-name` | `otel-service-name` |
| `jaeger-propagation-format` | `N/A` | | `jaeger-propagation-format` | `N/A` |
| `jaeger-sampler-type` | `otel-sampler` | | `jaeger-sampler-type` | `otel-sampler` |
| `jaeger-sampler-param` | `otel-sampler` | | `jaeger-sampler-param` | `otel-sampler` |
| `jaeger-sampler-host` | `N/A` | | `jaeger-sampler-host` | `N/A` |
| `jaeger-sampler-port` | `N/A` | | `jaeger-sampler-port` | `N/A` |
| `jaeger-trace-context-header-name` | `N/A` | | `jaeger-trace-context-header-name` | `N/A` |
| `jaeger-debug-header` | `N/A` | | `jaeger-debug-header` | `N/A` |
| `jaeger-baggage-header` | `N/A` | | `jaeger-baggage-header` | `N/A` |
| `jaeger-tracer-baggage-header-prefix` | `N/A` | | `jaeger-tracer-baggage-header-prefix` | `N/A` |
| `datadog-collector-port` | `otlp-collector-port` | | `datadog-collector-port` | `otlp-collector-port` |
| `datadog-service-name` | `otel-service-name` | | `datadog-service-name` | `otel-service-name` |
| `datadog-environment` | `N/A` | | `datadog-environment` | `N/A` |
| `datadog-operation-name-override` | `N/A` | | `datadog-operation-name-override` | `N/A` |
| `datadog-priority-sampling` | `otel-sampler` | | `datadog-priority-sampling` | `otel-sampler` |
| `datadog-sample-rate` | `otel-sampler-ratio` | | `datadog-sample-rate` | `otel-sampler-ratio` |