Skip to main content
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 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.
Store your API token in a secure location. If you lose your token, you must create a new service account.

​
Define the Collector manifest

  1. Download the example manifest.
  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 Chronosphere 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 the Chronosphere Observability Platform. To view the release notes, in the navigation menu select More information > Release notes, and then click the Collector tab.
  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 Observability Platform 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.
Installing the Collector grants permissions to read metadata about pods scheduled on the local node. Review your tracing-chronocollector.yaml manifest carefully before applying it.
  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 Observability Platform tenant.
  1. In the navigation menu, click Go to Admin and then select Analyzers > Live Telemetry.
  2. Click the Traces tab.
  3. Click Capture live data to display the stream of incoming spans. The default grouping shows spans by service (__service__), but you can include additional tags to group by such as __trace_id__ and __span_id__.