istio.io/istio@v0.0.0-20240520182934-d79c90f27776/samples/open-telemetry/tracing/README.md (about)

     1  # Open Telemetry Tracing
     2  
     3  This sample demonstrates the support for the OpenTelemetry tracing provider with the Telemetry API.
     4  
     5  ## Start otel-collector service
     6  
     7  First, deploy the `otel-collector` backend with simple configuration.
     8  
     9  ```bash
    10  kubectl -n <namespace> apply -f ../otel.yaml
    11  ```
    12  
    13  In this example, we use `observability` as the namespace to deploy the `otel-collector` backend:
    14  
    15  ```bash
    16  kubectl create namespace observability
    17  kubectl -n observability apply -f ../otel.yaml
    18  ```
    19  
    20  The otel-collector will create a grpc receiver on port `4317`, and later the sidecars will report trace information to this grpc port. You can find more details from [here](https://github.com/open-telemetry/opentelemetry-collector).
    21  
    22  Below is the configuration:
    23  
    24  ```yaml
    25  receivers:
    26    otlp:
    27      protocols:
    28        grpc:
    29        http:
    30  processors:
    31    batch:
    32  exporters:
    33    logging:
    34      loglevel: debug
    35  service:
    36    pipelines:
    37      logs:
    38        receivers: [otlp]
    39        processors: [batch]
    40        exporters: [logging]
    41  ```
    42  
    43  In this example, `Jaeger` is the exporter for gathering the traces. Assuming you have already deployed Jaeger as your tracing system with [this](https://istio.io/latest/docs/ops/integrations/jaeger/) installation, you are good to go to the next steps. If you already have your own `Jaeger` deployed, you may need to modify the otel collector config. The configmap name is `opentelemetry-collector-conf` in the namespace you deployed the otel collector, and the related config is defined as:
    44  
    45  ```yaml
    46  exporters:
    47    jaeger:
    48      endpoint: jaeger-collector.istio-system.svc.cluster.local:14250
    49      tls:
    50        insecure: true
    51      sending_queue:
    52        enabled: true
    53      retry_on_failure:
    54        enabled: true
    55  service:
    56    pipelines:
    57      traces:
    58        exporters:
    59        - jaeger
    60  ```
    61  
    62  You need to modify the jaeger exporter endpoint with the one you deployed, in this case it's `jaeger-collector.istio-system.svc.cluster.local:14250`.
    63  
    64  If you have not deployed the `Jaeger` service, you can follow [this](https://istio.io/latest/docs/ops/integrations/jaeger/) installation to install the service.
    65  
    66  You may also choose any existing tracing system if you have, and you should change the exporter settings in the configmap mentioned above.
    67  
    68  You may also choose to use your own otel collector if you have, and the key part is to have the `otlp` grpc protocol receiver to receive the traces. One important thing is to make sure your otel collector service's grpc port starts with `grpc-` prefix, which is like:
    69  
    70  ```yaml
    71  spec:
    72    ports:
    73      - name: grpc-otlp
    74        port: 4317
    75        protocol: TCP
    76        targetPort: 4317
    77  ```
    78  
    79  Otherwise the traces may not be reported.
    80  
    81  ## Update mesh config
    82  
    83  Install or update Istio with the `demo` profile to make sure you have the OpenTelemetry tracing provider enabled:
    84  
    85  ```bash
    86  istioctl install --set profile=demo -y
    87  ```
    88  
    89  Or ensure you have the following additional mesh config set in your Istio:
    90  
    91  ```yaml
    92  mesh: |-
    93    extensionProviders:
    94    - name: otel-tracing
    95      opentelemetry:
    96        port: 4317
    97        service: opentelemetry-collector.observability.svc.cluster.local
    98  ```
    99  
   100  Make sure the service name matches the one you deployed if you select a different namespace.
   101  
   102  ## Apply the Telemetry resource to report traces
   103  
   104  Next, add a Telemetry resource that tells Istio to send trace records to the OpenTelemetry collector.
   105  
   106  ```bash
   107  kubectl -n <namespace> apply -f ./telemetry.yaml
   108  ```
   109  
   110  In this example, we deploy it to the default namespace, which is where the sample apps
   111  from the [getting started](https://istio.io/latest/docs/setup/getting-started) are also deployed.
   112  
   113  ```bash
   114  kubectl apply -f ./telemetry.yaml
   115  ```
   116  
   117  The core config is:
   118  
   119  ```yaml
   120  tracing:
   121  - providers:
   122    - name: otel-tracing
   123    randomSamplingPercentage: 0
   124  ```
   125  
   126  As you see, the `randomSamplingPercentage` is 0, which means the tracing is still not enabled because of `0` sampling percentage. The tracing can be opt-on by increasing the `randomSamplingPercentage` value to `1-100`. The `Telemetry` resource can also be manipulated in workload/namespace/global levels, you can check [here](https://istio.io/latest/docs/reference/config/telemetry/) for more config examples.
   127  
   128  ## Check tracing results
   129  
   130  If you have followed [this](https://istio.io/latest/docs/setup/getting-started/) getting started steps, you have the sample bookinfo applications installed. Try to make some requests to the productpage to generate some traces.
   131  
   132  Then open up the `Jaeger` dashboard with:
   133  
   134  ```bash
   135  istioctl dashboard jaeger
   136  ```
   137  
   138  You will see the requests' trace records.
   139  
   140  ## Cleanup
   141  
   142  ```bash
   143  kubectl -n observability delete -f ./telemetry.yaml
   144  kubectl -n observability delete -f ../otel.yaml
   145  ```