Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sawmills.ai/llms.txt

Use this file to discover all available pages before exploring further.

This guide explains how to send telemetry data (logs, metrics, traces) to the Sawmills Collector running as a deployment within a Kubernetes (K8s) cluster. You can choose to send data from within the cluster (internal) or from outside the cluster (external).

​
1. Sending Telemetry Data Internally (Within the Cluster)

When sending telemetry data from applications or services within the Kubernetes cluster, you can leverage the cluster’s internal DNS to route data to the Sawmills Collector service.
  1. Send Data to the Sawmills Collector’s Internal DNS Address
    Use the Sawmills Collector service DNS address within the cluster: <collector-service>.<namespace>.svc.cluster.local. Kubernetes automatically manages this DNS for services, allowing pods to communicate with the Sawmills Collector by using this DNS name.
Note: If the collector load balancer is enabled, send telemetry sources to the source-facing load balancer service. With the default resource base name, that service is sawmills-collector. Without the load balancer, send telemetry sources to the regular collector service.
  1. Using Headless Services for Direct Pod Communication
    For scenarios where you need direct communication with specific collector pods (e.g., load balancing, service discovery), you can use a headless service. For example: <collector-headless-service>.<namespace>.svc.cluster.local. A headless service (ClusterIP: None) allows direct pod-to-pod communication and is particularly useful when you need to bypass the default load balancing behavior of Kubernetes services.
  2. Set the Collector’s Port
    The Sawmills Collector typically listens on a specific port (e.g., 4317 for OTLP/gRPC). Ensure your application is configured to send data to the correct port on the collector.
  3. Verify Data Flow
    Check that data is successfully flowing from your applications to the Sawmills Collector. The collector should receive, process, and potentially forward this data to a specified backend (e.g., Prometheus, Grafana) for further analysis.

​
2. Sending Telemetry Data Externally (Outside the Cluster)

If your data source is external to the Kubernetes cluster, you’ll need to expose the Sawmills Collector service to external traffic.

​
Options to Expose the Collector:

  1. NodePort Service: A simpler method, mainly for testing purposes, exposing the service on a node’s IP address. Creating a NodePort Service You can use the following YAML to create a NodePort service that exposes the Sawmills Collector to external traffic:
Use the same selector labels as the source-facing collector service you want to expose. Do not select only by release instance, because load balancer mode uses the same release instance label on both load balancer and backend collector pods. 
apiVersion: v1
kind: Service
metadata:
  name: sawmills-collector-nodeport
spec:
  type: NodePort
  selector:
    app.kubernetes.io/instance: <collector-release-name>
    app.kubernetes.io/name: <source-facing-service-selector-name>
  ports:
    - protocol: TCP
      port: 80
      targetPort: 8080
  1. Kubernetes Ingress: Suitable for production, an ingress provides flexibility in routing external traffic to the collector service.
  • Prerequisites
    • An Ingress controller must be installed in your cluster (e.g., NGINX Ingress Controller or Traefik).
    • A DNS entry pointing to your Ingress controller’s IP (or Load Balancer IP if you’re on a cloud provider).
  • Example creates an Ingress resource that directs traffic from a specific external path (e.g., /sawmills) to the Sawmills Collector service.
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: sawmills-collector-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  rules:
    - host: example.com # Replace with your domain name
      http:
        paths:
          - path: /sawmills # Path for external access
            pathType: Prefix
            backend:
              service:
                name: <collector-service>
                port:
                  number: 8080 # The port on which the Sawmills Collector listens internally
  # Optional: TLS configuration for secure HTTPS access
  tls:
    - hosts:
        - example.com # Replace with your domain name
      secretName: sawmills-tls # A pre-created TLS secret for HTTPS