Kubernetes Collector installation to receive traces

The recommended way to install the Collector to receive trace data is with a Kubernetes Deployment, with a service in front to receive trace data. Your tracing app pushes trace data to the service, which the Collector receives the data from.

Chronosphere recommends instrumenting your app to emit span data in OpenTelemetry format (opens in a new tab) if you haven't already invested in legacy tracing instrumentation. You can configure the Collector to accept OpenTelemetry traces in both gRPC and JSON over HTTP formats. A single Collector can accept OpenTelemetry traces in both of these formats simultaneously.

The Collector manifest linked in this page uses OpenTelemetry by default, but you can modify the manifest to use other supported formats, such as Jaeger or Zipkin.

To install the Collector:

1. Create an API token.
2. Define the Collector manifest.
3. Create a Kubernetes secret.
4. Install the Collector.
5. Verify the Collector.

Create an API token

To interact with the Collector, you must create a service account. You must be a member of a team with the SysAdmin role to create a new service account. Chronosphere recommends creating a restricted service account with a write-only scope. Use the generated API token in your Kubernetes Secret to authenticate with the Collector.

Define the Collector manifest

1. Download the example manifest (opens in a new tab).

2. Locate the spec.template.spec.containers.image YAML collection and change vVERSION_NUMBER to the version of the Collector you want to install. For example, v0.100.1:

   spec:
     template:
       spec:
         containers:
           - image: gcr.io/chronosphereio/chronocollector:vVERSION_NUMBER

   Chronosphere supports Collector versions for a year from release. You can find a full list of versions and release dates in the Collector release notes located in your Chronosphere app at Help > Release notes > Collector.

3. Define the format you want the Collector to receive spans in, such as OpenTelemetry, Jaeger or Zipkin. The following example enables receiving spans in OpenTelemetry format:

   You can only enable one format of traces to receive. You must remove or comment out any additional trace formats from the spans YAML collection.

   1. In the spans YAML collection, define the format you want to receive spans for. For example, to receive spans in OpenTelemetry format:

      spans:
        enabled: true
        compression:
          enabled: true
        otel:
          enabled: true
          listenAddress: 0.0.0.0:4317

      If you want to accept OpenTelemetry traces in JSON format over HTTP, add the following http definitions to your YAML collection under spans. This YAML collection starts an HTTP receiver that accepts traces in both gRPC and JSON over HTTP formats.

      spans:
      ...
        otel:
          enabled: true
          listenAddress: 0.0.0.0:4317
          httpEnabled: true
          httpListenAddress: 0.0.0.0:4318

   2. For the tracing Service, modify the spec.ports.name YAML collection to reflect the trace format you want to use. For example, to receive spans in OpenTelemetry format:

      kind: Service
      ...
      spec:
        ports:
        - name: otel
          port: 4317
          protocol: TCP
          targetPort: otel

4. Save your Collector manifest, which you apply in a subsequent step after creating a Kubernetes secret.

Create a Kubernetes secret

Create a Kubernetes Secret that includes the API token from your service account, plus a custom domain address.

1. Add base64 encoding to your domain name and API token:

   echo -n "ADDRESS" | base64
   echo -n "API_TOKEN" | base64

   Replace the following:

   • ADDRESS: Your company name prefixed to your Chronosphere instance that ends in .chronosphere.io:443. For example, MY_COMPANY.chronosphere.io:443.
   • API_TOKEN: The API token generated from your service account.

2. Copy the values that output to your terminal, which you add as part of your Kubernetes Secret in the next step.

3. In your tracing-chronocollector.yaml file, locate the following YAML collection and replace values for address and api-token with the encoded values that you copied from your terminal.

   apiVersion: v1
   data:
     address: ENCODED_ADDRESS
     api-token: ENCODED_API_TOKEN
   kind: Secret
   metadata:
     labels:
       app: chronocollector-tracing
     name: chronosphere-tracing-secret
     namespace: default
   type: Opaque

   Another option is to add the ADDRESS and API_TOKEN directly to the Kubernetes cluster using kubectl:

   kubectl create secret generic chronosphere-secret \
     --from-literal=api-token=API_TOKEN \
     --from-literal=address=ADDRESS

4. Save and close your tracing-chronocollector.yaml file.

Now you're ready to install the Collector.

Install the Collector

To install the Collector, apply the tracing-chronocollector.yaml manifest that you configured.

1. Apply the manifest.

   kubectl apply -f path/to/tracing-chronocollector.yaml

2. Confirm the deployment is up and running, and view the logs of the pod:

   kubectl get pods

   The output is similar to the following:

   NAME                    READY   STATUS    RESTARTS   AGE
   chronocollector-tracing-POD_NAME   1/1     Running   0          1m

3. View the pod logs to ensure there are no errors:

   kubectl logs chronocollector-tracing-POD_NAME

   Replace POD_NAME with the name of the Kubernetes pod where your Collector instance is running.

Verify the Collector

After installing the Collector, verify that it's sending traces to your Chronosphere tenant.

1. Open the Chronosphere app and in the navigation menu select Exploring > Trace Analyzer.
2. Click Run to display the stream of incoming spans. The default grouping shows spans by service (__svc__), but you can include additional tags to group by such as __trace_id__ and __span_id__.