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:
- Create an API token.
- Define the Collector manifest.
- Create a Kubernetes secret.
- Install the Collector.
- Verify the Collector.
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.
Download the example manifest (opens in a new tab).
spec.template.spec.containers.imageYAML collection and change
vVERSION_NUMBERto the version of the Collector you want to install. For example,
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.
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
spansYAML 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
httpdefinitions 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
For the tracing
Service, modify the
spec.ports.nameYAML 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
Save your Collector manifest, which you apply in a subsequent step after creating a Kubernetes secret.
Create a Kubernetes
Secret that includes the API token from your service account,
plus a custom domain address.
base64encoding to your domain name and API token:
echo -n "ADDRESS" | base64 echo -n "API_TOKEN" | base64
ADDRESS: Your company name prefixed to your Chronosphere instance that ends in
.chronosphere.io:443. For example,
API_TOKEN: The API token generated from your service account.
Copy the values that output to your terminal, which you add as part of your Kubernetes
Secretin the next step.
tracing-chronocollector.yamlfile, locate the following YAML collection and replace values for
api-tokenwith 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
API_TOKENdirectly to the Kubernetes cluster using
kubectl create secret generic chronosphere-secret \ --from-literal=api-token=API_TOKEN \ --from-literal=address=ADDRESS
Save and close your
Now you're ready to install the Collector.
To install the Collector, apply the
tracing-chronocollector.yaml manifest that you
Installing the Collector grants permissions to read metadata about pods scheduled on
the local node. Review your
tracing-chronocollector.yaml manifest carefully before
Apply the manifest.
kubectl apply -f path/to/tracing-chronocollector.yaml
Confirm the deployment is up and running, and view the logs of the pod:
kubectl get pods NAME READY STATUS RESTARTS AGE chronocollector-tracing-POD_NAME 1/1 Running 0 1m
View the pod logs to ensure there are no errors:
kubectl logs chronocollector-tracing-POD_NAME ...
POD_NAME: the name of the Kubernetes pod where your Collector instance is running.
After installing the Collector, verify that it's sending traces to your Chronosphere tenant.
- Open the Chronosphere app and in the navigation menu select Exploring > Trace Analyzer.
- 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