Add docs and helm values for Kubernetes Monitoring

.github/workflows/build.yml

@@ -7,7 +7,7 @@ on:
 
 jobs:
   build_linux:
-    runs-on: ubuntu-latest-4-cores
+    runs-on: ubuntu-20.04
     steps:
       - name: Checkout Sources
         uses: actions/checkout@v4
@@ -23,36 +23,37 @@ jobs:
       - name: Build
         working-directory: ./collector
         run: make build-linux
-  build_darwin:
-    runs-on: macos-14
-    steps:
-      - name: Checkout Sources
-        uses: actions/checkout@v4
-      - name: Setup Go
-        uses: actions/setup-go@v5
-        with:
-          go-version: "1.20"
-          check-latest: true
-      - name: Install builder
-        working-directory: ./collector
-        run: |
-            go install go.opentelemetry.io/collector/cmd/[email protected]   
-      - name: Build
-        run: make build-darwin
-  build_windows:
-    runs-on: ubuntu-20.04
-    steps:
-      - name: Checkout Sources
-        uses: actions/checkout@v4
-      - name: Setup Go
-        uses: actions/setup-go@v5
-        with:
-          go-version: "1.20"
-          check-latest: true
-      - name: Install builder
-        working-directory: ./collector
-        run: |
-            go install go.opentelemetry.io/collector/cmd/[email protected]      
-      - name: Build
-        working-directory: ./collector
-        run: make build-windows
+#   build_darwin:
+#     runs-on: macos-14
+#     steps:
+#       - name: Checkout Sources
+#         uses: actions/checkout@v4
+#       - name: Setup Go
+#         uses: actions/setup-go@v5
+#         with:
+#             go-version: '~1.21.5'
+#             check-latest: true
+#       - name: Install builder
+#         working-directory: ./collector
+#         run: |
+#             go install go.opentelemetry.io/collector/cmd/[email protected]   
+#       - name: Build
+#         working-directory: ./collector
+#         run: make build-darwin
+#   build_windows:
+#     runs-on: ubuntu-20.04
+#     steps:
+#       - name: Checkout Sources
+#         uses: actions/checkout@v4
+#       - name: Setup Go
+#         uses: actions/setup-go@v5
+#         with:
+#             go-version: '~1.21.5'
+#             check-latest: true
+#       - name: Install builder
+#         working-directory: ./collector
+#         run: |
+#             go install go.opentelemetry.io/collector/cmd/[email protected]      
+#       - name: Build
+#         working-directory: ./collector
+#         run: make build-windows

.github/workflows/test.yml

@@ -7,7 +7,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-20.04, macos-14, windows-2022-8-cores]
+        #os: [ubuntu-20.04, macos-14, windows-2022-8-cores]
+        os: [ubuntu-20.04]
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout Sources

collector/config-k8s/values-cluster.yaml

@@ -0,0 +1,95 @@
+# based on: https://docs.honeycomb.io/integrations/kubernetes/values-files/values-deployment.yaml
+mode: deployment
+
+extraEnvs:
+  - name: CLOUDOBS_TOKEN
+    valueFrom:
+      secretKeyRef:
+        name: servicenow-cloudobs-token
+        key: token
+
+# We only want one of these collectors - any more and we'd produce duplicate data
+replicaCount: 1
+
+presets:
+  # enables the k8sclusterreceiver and adds it to the metrics pipelines
+  clusterMetrics:
+    enabled: true
+  # enables the k8sobjectsreceiver to collect events only and adds it to the logs pipelines
+  kubernetesEvents:
+    enabled: true
+
+# Uncomment to use the ServiceNow build of the OpenTelemetry collector
+#image:
+#  repository: ghcr.io/lightstep/sn-collector/sn-collector-experimental
+#  pullPolicy: Always
+#  tag: latest
+#command:
+#  name: otelcol-servicenow
+
+config:
+  receivers:
+    k8s_cluster:
+      collection_interval: 30s
+    jaeger: null
+    zipkin: null
+  processors:
+    transform/events:
+      error_mode: ignore
+      log_statements:
+        - context: log
+          statements:
+            # adds a new watch-type attribute from the body if it exists
+            - set(attributes["watch-type"], body["type"]) where IsMap(body) and body["type"] != nil
+
+            # create new attributes from the body if the body is an object
+            - merge_maps(attributes, body, "upsert") where IsMap(body) and body["object"] == nil
+            - merge_maps(attributes, body["object"], "upsert") where IsMap(body) and body["object"] != nil
+
+            # Transform the attributes so that the log events use the k8s.* semantic conventions
+            - merge_maps(attributes, attributes[ "metadata"], "upsert") where IsMap(attributes[ "metadata"])
+            - set(attributes["k8s.pod.name"], attributes["regarding"]["name"]) where attributes["regarding"]["kind"] == "Pod"
+            - set(attributes["k8s.node.name"], attributes["regarding"]["name"]) where attributes["regarding"]["kind"] == "Node"
+            - set(attributes["k8s.job.name"], attributes["regarding"]["name"]) where attributes["regarding"]["kind"] == "Job"
+            - set(attributes["k8s.cronjob.name"], attributes["regarding"]["name"]) where attributes["regarding"]["kind"] == "CronJob"
+            - set(attributes["k8s.namespace.name"], attributes["regarding"]["namespace"]) where attributes["regarding"]["kind"] == "Pod" or attributes["regarding"]["kind"] == "Job" or attributes["regarding"]["kind"] == "CronJob"
+
+            # Transform the type attribtes into OpenTelemetry Severity types.
+            - set(severity_text, attributes["type"]) where attributes["type"] == "Normal" or attributes["type"] == "Warning"
+            - set(severity_number, SEVERITY_NUMBER_INFO) where attributes["type"] == "Normal"
+            - set(severity_number, SEVERITY_NUMBER_WARN) where attributes["type"] == "Warning"
+
+  exporters:
+    # Uncomment if using the ServiceNow build of the OpenTelemetry collector
+    # servicenow/events:
+    #   instance_events_url: ${env:SERVICENOW_EVENTS_URL}
+    #   username: ${env:SERVICENOW_EVENTS_USERNAME}
+    #   password: ${env:SERVICENOW_EVENTS_PASSWORD}
+    otlp/cloudobs:
+      endpoint: "ingest.lighstep.com:443"
+      headers:
+        "lightstep-access-token": "${env:CLOUDOBS_TOKEN}"
+
+  service:
+    pipelines:
+      traces: null
+      # Send metrics about the collector itself to Cloud Observability
+      metrics/collector-monitoring:
+        receivers: [ prometheus ]
+        processors: [ batch ]
+        exporters:  [ otlp/cloudobs ]
+      metrics:
+        exporters: [ otlp/cloudobs ]
+      logs:
+        processors: [ memory_limiter, transform/events, batch ]
+        exporters: [ otlp/cloudobs ]
+
+ports:
+  jaeger-compact:
+    enabled: false
+  jaeger-thrift:
+    enabled: false
+  jaeger-grpc:
+    enabled: false
+  zipkin:
+    enabled: false

collector/otelcol-builder.yaml

@@ -8,6 +8,9 @@ dist:
 exporters:
   - gomod:
       go.opentelemetry.io/collector/exporter/debugexporter v0.95.0
+  # Logging exporter is deprecated, but it's here to support the default OpenTelemetry Collector Helm chart as of 2/23/24
+  - gomod:
+      go.opentelemetry.io/collector/exporter/loggingexporter v0.95.0
   - gomod:
       go.opentelemetry.io/collector/exporter/otlpexporter v0.95.0
   - gomod:
@@ -21,6 +24,9 @@ processors:
     import: github.com/open-telemetry/otel-arrow/collector/processor/concurrentbatchprocessor
   - gomod:
       go.opentelemetry.io/collector/processor/batchprocessor v0.95.0
+  # We don't recommend memory limiter, but it's here to support the default OpenTelemetry Collector Helm chart as of 2/23/24
+  - gomod:
+      go.opentelemetry.io/collector/processor/memorylimiterprocessor v0.95.0
   - gomod:
       github.com/open-telemetry/opentelemetry-collector-contrib/processor/resourcedetectionprocessor v0.95.0
   - gomod:
@@ -49,6 +55,8 @@ receivers:
       github.com/open-telemetry/opentelemetry-collector-contrib/receiver/k8seventsreceiver v0.95.0 
   - gomod:
       github.com/open-telemetry/opentelemetry-collector-contrib/receiver/hostmetricsreceiver v0.95.0 
+  - gomod:
+      github.com/open-telemetry/opentelemetry-collector-contrib/receiver/k8sobjectsreceiver v0.95.0 
   - gomod:
       github.com/open-telemetry/opentelemetry-collector-contrib/receiver/k8sclusterreceiver v0.95.0 
   - gomod:

docs/monitor-kubernetes.md

@@ -1,46 +1,71 @@
 ## Monitor Kubernetes with the ServiceNow Collector
 
 | Kuberenetes Distibution                        | Support Status            | Architecture |
-| ---------------------------------------------- | ------------------ ------ | ------------ |
+| ---------------------------------------------- | ------------------------- | ------------ |
 | GKE (Google Cloud)                             | last three major versions | ARM, AMD     |
 | EKS (AWS)                                      | last three major versions | ARM, AMD     |
 | AKS (Azure)                                    | last three major versions | ARM, AMD     |
 | Kubernetes                                     | last three major versions | ARM, AMD     |
 
-* **Note:** We recommend Red Hat OpenShift customers should use the [Red Hat OpenTelemetry Distribution](https://docs.openshift.com/container-platform/4.12/otel/otel-using.html).
+* **Note:** We recommend Red Hat OpenShift customers use the [Red Hat OpenTelemetry Distribution](https://docs.openshift.com/container-platform/4.12/otel/otel-using.html).
 
 ### Deploy for Kubernetes monitoring with The OpenTelemetry Operator and Helm
 
-> This is an example only. We recommend using the official OpenTelemetry Operator Helm chart for deploying to production.
+#### Requirements
 
-All of the following assume you are installing the Operator in the `default` cluster namespace and you have `helm` v3 installed.
+* `helm` v3
+* Kubernetes cluster with local access via `kubectl`
+* ability to pull from the Docker image repository `ghcr.io/lightstep/sn-collector`
 
-1. Add OpenTelemetry Helm Charts.
-  - ```sh
-    helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
-    helm repo update
-    ```
+#### 1. Add OpenTelemetry Helm Repository
 
-2. Install charts. This installs the Operator with an automatically-generated self-signed certificate. For other options, see ["TLS Certificate Requirement"](https://github.com/open-telemetry/opentelemetry-helm-charts/tree/main/charts/opentelemetry-operator#tls-certificate-requirement) in OpenTelemetry Operator documentation.
-  - ```sh
-    helm install \
-        --set admissionWebhooks.certManager.enabled=false \
-        --set admissionWebhooks.certManager.autoGenerateCert=true \
-        opentelemetry-operator open-telemetry/opentelemetry-operator
-    ```
+We use the OpenTelemetry Helm charts to install the OpenTelemetry Operator. The Operator makes it easy to scale and configure collectors in Kubernetes.
 
-3. Set credentials for your ServiceNow instance and Cloud Observability.
-  - ```sh
-    export LS_TOKEN='<your-token>'
-    kubectl create secret generic ls-token-secret -n default --from-literal='LS_TOKEN=$LS_TOKEN'
+```sh
+helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
+helm repo update
+```
 
-    # Set password for Event Manangement user on your instances
-    export MID_INSTANCE_EVENTS_PASSWORD='<your-mid-user-pw>'
-    kubectl create secret generic mid-instance-events-password -n default --from-literal='MID_INSTANCE_EVENTS_PASSWORD=$MID_INSTANCE_EVENTS_PASSWORD'
-    ```
+#### 2. Create a ServiceNow Namespace
 
-4. Deploy an OpenTelemetry Collector. The following uses the deployment example from the `collector/examples/` directory. Before applying you *must* edit the `k8s-deployment.yaml` file and set your username, instance URL, and cluster name. 
+This namespace is where the OpenTelemetry components will live in your cluster.
 
-  - ```sh
-    kubectl apply -f collector/examples/k8s-deployment.yaml
-    ```
+```sh
+kubectl create namespace servicenow
+```
+
+#### 3. Set credentials
+
+Paste your token carefully and escape it in single-quotes so special characters aren't interpreted by your shell.
+
+```sh
+export CLOUDOBS_TOKEN='<your-cloudobs-token>'
+kubectl create secret generic servicenow-cloudobs-token \
+    -n servicenow --from-literal='token=$LS_TOKEN'
+```
+
+Set username and password for Event Manangement.
+
+```sh
+export SERVICENOW_EVENTS_USERNAME='<your-mid-user>'
+kubectl create secret generic servicenow-events-user \
+-n servicenow --from-literal='USERNAME=$SERVICENOW_EVENTS_USERNAME'
+
+export SERVICENOW_EVENTS_PASSWORD='<your-mid-user-pw>'
+kubectl create secret generic servicenow-events-password \
+-n servicenow --from-literal='PASSWORD=$SERVICENOW_EVENTS_PASSWORD'
+```
+
+#### 3. Deploy ServiceNow Collector for Cluster Monitoring
+
+You're now ready to deploy a collector to your cluster to collect cluster-level metrics and events.
+
+```sh
+helm upgrade otel-collector-cluster open-telemetry/opentelemetry-collector --install --namespace servicenow --values https://raw.githubusercontent.com/lightstep/sn-collector/main/collector/config-k8s/values-cluster.yaml
+```
+
+The pod will deploy after a few seconds, to check status and for errors, run:
+
+```sh
+kubectl get pods -n servicenow
+```

docs/monitor-linux.md

@@ -11,7 +11,11 @@
 
 Gather system metrics from a Linux system using an installed software package. Use this for servers and hosts that **do not** have Docker or a container runtime.
 
-1. Download the appropriate package for your system and architecture from the Releases page of this repository.
+1. Download the appropriate package for your system and CPU architecture from the Releases page of this repository. 
+    - If you're not sure about what architecture your system is using, inspect the output of the `arch` command.
+    ```sh
+    arch
+    ```
 
 2. Install the downloaded package using the appropriate package manager for your Linux distribution.
   - RPM (RHEL, CentOS, Amazon Linux) package with `yum`: