Stackrox Collector

https://github.com/stackrox/collector
Admin
Stackrox Collector is a runtime data collection agent that runs on every node with strict...
Tokens:20,760
Snippets:209
Trust Score:10
License:Apache-2.0
Update:7 months ago
Show doc for...
Tokens:
Raw
### Collector Startup Diagnostics Log Example

Source: https://github.com/stackrox/collector/blob/master/docs/troubleshooting.md

An example log output showing the Collector's startup diagnostics. It indicates whether the Collector successfully connected to Sensor and loaded the eBPF probe.

```log
[INFO    2025/07/24 10:05:54] == Collector Startup Diagnostics: ==
[INFO    2025/07/24 10:05:54]  Connected to Sensor?       false
[INFO    2025/07/24 10:05:54]  Kernel driver candidates:
[INFO    2025/07/24 10:05:54]    core_bpf (available)
[INFO    2025/07/24 10:05:54]  Driver loaded into kernel: core_bpf
[INFO    2025/07/24 10:05:54] ====================================
```

--------------------------------

### Build and Test with vcpkg and CMake

Source: https://github.com/stackrox/collector/blob/master/docs/how-to-start.md

Commands to compile the project using CMake presets and execute unit tests via ctest.

```bash
cmake --preset=vcpkg
cmake --build cmake-build/vcpkg -j$(nproc)
ctest --test-dir cmake-build/vcpkg
```

--------------------------------

### Get Runtime Configuration (Bash)

Source: https://github.com/stackrox/collector/blob/master/docs/troubleshooting.md

Fetches the current runtime configuration of the collector. This is a simple GET request to the specified endpoint.

```bash
$ curl "http://<collector>:8080/state/runtime-config"
```

--------------------------------

### Install Build Dependencies on Fedora

Source: https://github.com/stackrox/collector/blob/master/docs/how-to-start.md

System packages required to compile the collector and its dependencies on a Fedora-based Linux distribution.

```bash
dnf install -y gcc clang make cmake zip unzip tar autoconf automake libtool kernel-devel perl libbpf-devel bpftool libcap-ng-devel libuuid-devel
```

--------------------------------

### GET /state/runtime-config

Source: https://github.com/stackrox/collector/blob/master/docs/troubleshooting.md

Retrieves the current runtime configuration of the collector.

```APIDOC
## GET /state/runtime-config

### Description
Obtains the current runtime configuration settings for the collector.

### Method
GET

### Endpoint
/state/runtime-config

### Response
#### Success Response (200)
- **config** (object) - The current runtime configuration object.
```

--------------------------------

### Mount and Configure Minikube for Development

Source: https://github.com/stackrox/collector/blob/master/docs/how-to-start.md

Commands to initialize Minikube with NFS sharing and create symlinks to ensure the collector repository is accessible within the cluster environment.

```bash
$ minikube start --nfs-share='/path/to/collector'
$ minikube ssh
$ sudo ln -s /nfsshare/path/to/collector /path/to/collector
```

--------------------------------

### Configure VSCode Source Mapping

Source: https://github.com/stackrox/collector/blob/master/docs/how-to-start.md

Configuration snippet for VSCode launch.json to map internal container paths to local project directories for debugging.

```json
"sourceFileMap":{
    "/src": "/Path/To/collector/collector"
}
```

--------------------------------

### Provision RHEL VMs for Testing

Source: https://github.com/stackrox/collector/blob/master/ansible/README.md

Example of using Ansible playbooks to create and provision Red Hat Enterprise Linux (RHEL) VMs for testing. The 'VM_TYPE' variable specifies the OS, and tags like 'setup' and 'provision' control the playbook stages.

```bash
VM_TYPE=rhel ansible-playbook -i dev vm-lifecycle.yml --tags setup
ansible-playbook -i dev vm-lifecycle.yml --tags provision
```

--------------------------------

### Clone Repository and Build Collector Image

Source: https://github.com/stackrox/collector/blob/master/docs/how-to-start.md

Commands to fetch the repository with submodules and trigger the automated build process for the collector container image.

```bash
git clone --recurse-submodules https://github.com/stackrox/collector.git
cd collector
make image
```

--------------------------------

### Build Collector Image in Minikube

Source: https://github.com/stackrox/collector/blob/master/docs/how-to-start.md

Configures the local shell to use the Minikube docker engine and triggers the build process for the collector image.

```bash
$ eval $(minikube -p minikube docker-env)
$ make image
```

--------------------------------

### Configure Collector Runtime Settings

Source: https://github.com/stackrox/collector/blob/master/docs/references.md

Examples of YAML configuration for the Collector runtime, including enabling external IPs and setting connection limits. These configurations can be applied via file mounts or Kubernetes ConfigMaps.

```yaml
networking:
  externalIps:
    enabled: ENABLED
  maxConnectionsPerMinute: 1234
```

```yaml
networking:
  externalIps:
    enabled: ENABLED
    direction: EGRESS
```

--------------------------------

### Enable Standalone Mode

Source: https://github.com/stackrox/collector/blob/master/docs/how-to-start.md

Methods to enable standalone mode where the collector outputs gRPC messages to stdout instead of connecting to a server.

```yaml
environment:
  - GRPC_SERVER=
```

```bash
collector --grpc-server=
```

--------------------------------

### GET /state/network/connection

Source: https://github.com/stackrox/collector/blob/master/docs/troubleshooting.md

Retrieves an array of all network connections currently known to the collector.

```APIDOC
## GET /state/network/connection

### Description
Returns an array of network connections known to the collector. Afterglow is not applied to this data.

### Method
GET

### Endpoint
/state/network/connection

### Parameters
#### Query Parameters
- **container** (string) - Optional - Filter results by a specific container_id.
- **normalize** (boolean) - Optional - Set to false to disable normalization of connections. Defaults to true.

### Request Example
curl "http://<collector>:8080/state/network/connection?container=c6f030bc4b42&normalize=false"

### Response
#### Success Response (200)
- **connections** (object) - Map of container IDs to their respective connection lists.

#### Response Example
{
  "c6f030bc4b42" : [
    {
      "active" : true,
      "l4proto" : "TCP",
      "port" : 443,
      "to" : "10.96.0.1"
    }
  ]
}
```

--------------------------------

### Run Collector via Docker Compose

Source: https://github.com/stackrox/collector/blob/master/docs/how-to-start.md

A Docker Compose configuration to run the collector in privileged mode with a mock gRPC server for testing and event observation.

```yaml
version: "3.9"
services:
  collector:
    image: quay.io/stackrox-io/collector:<debuggable-collector-tag>
    container_name: collector-debug
    network_mode: host
    privileged: true
    environment:
      - GRPC_SERVER=localhost:9999
      - COLLECTOR_CONFIG={"logLevel":"debug","turnOffScrape":true,"scrapeInterval":2}
      - COLLECTION_METHOD=core-bpf
      - COLLECTOR_HOST_ROOT=/host
    volumes:
      - /var/run/docker.sock:/host/var/run/docker.sock:ro
      - /proc:/host/proc:ro
      - /etc:/host/etc:ro
      - /usr/lib:/host/usr/lib:ro
      - /sys/:/host/sys/:ro
      - /dev:/host/dev:ro
    depends_on:
      - grpc-server-debug
  grpc-server-debug:
    image: quay.io/rhacs-eng/grpc-server:latest
    container_name: grpc-server
    network_mode: host
    user: 1000:1000
    volumes:
      - /tmp:/tmp:rw
```

--------------------------------

### GET /metrics

Source: https://context7.com/stackrox/collector/llms.txt

Exposes performance metrics and system statistics in Prometheus format.

```APIDOC
## GET /metrics

### Description
Retrieves system performance metrics, including network scraping timers, event counters, and connection statistics.

### Method
GET

### Endpoint
/metrics

### Response
#### Success Response (200)
- **metrics** (text/plain) - Prometheus formatted metrics data.

### Response Example
# HELP rox_connections_total Amount of stored connections over time
# TYPE rox_connections_total summary
rox_connections_total{dir="out",peer="private",quantile="0.5"} 1558
```

--------------------------------

### Configure Collector for Metadata Access

Source: https://github.com/stackrox/collector/blob/master/docs/troubleshooting.md

YAML configuration snippet for the Collector DaemonSet to enable runtime configuration and mount necessary CRI sockets.

```yaml
spec:
  template:
    spec:
      containers:
        - name: collector
          env:
          - name: ROX_COLLECTOR_RUNTIME_CONFIG_ENABLED
            value: "true"
          volumeMounts:
          - mountPath: /host/run/containerd/containerd.sock
            mountPropagation: HostToContainer
            name: containerd-sock
          - mountPath: /host/run/crio/crio.sock
            mountPropagation: HostToContainer
            name: crio-sock
      volumes:
      - hostPath:
          path: /run/containerd/containerd.sock
        name: containerd-sock
      - hostPath:
          path: /run/crio/crio.sock
        name: crio-sock
```

--------------------------------

### Enable GRPC Tracing for Troubleshooting (Bash)

Source: https://github.com/stackrox/collector/blob/master/docs/troubleshooting.md

Enables detailed tracing for GRPC communication by setting the GRPC_TRACE environment variable. This helps diagnose connectivity issues between the collector and Sensor.

```bash
export GRPC_TRACE='*'
```

--------------------------------

### Install Ansible Dependencies

Source: https://github.com/stackrox/collector/blob/master/ansible/README.md

Installs Ansible and its required dependencies using pip. This is a prerequisite for running the provided Ansible playbooks. Ensure you have Python 3.9 or later installed.

```bash
pip3 install -r requirements.txt
```

--------------------------------

### Configure Google Test and Unit Tests (CMake)

Source: https://github.com/stackrox/collector/blob/master/collector/test/CMakeLists.txt

This CMake script finds the Google Test package and sets up unit tests. It iterates through C++ test files, creates executables for each, links them with the collector library and Google Test libraries, and registers them as CMake tests. It also includes conditional logic for specific test configurations and Valgrind integration.

```cmake
find_package(GTest CONFIG REQUIRED)

set(CMAKE_INCLUDE_CURRENT_DIR ON)

# Unit Tests
file(GLOB TEST_SRC_FILES ${PROJECT_SOURCE_DIR}/test/*.cpp)
foreach(test_file ${TEST_SRC_FILES})
    get_filename_component(test_name ${test_file} NAME_WE)
    add_executable("${test_name}" "${test_file}")

    target_link_libraries(${test_name} collector_lib)
    target_link_libraries(${test_name} GTest::gtest GTest::gtest_main GTest::gmock GTest::gmock_main)

    if(${test_name} STREQUAL "ConfigLoaderTest")
        target_sources(${test_name} PRIVATE proto/test-config.proto)
        target_include_directories(${test_name} PRIVATE proto)
        protobuf_generate(TARGET ${test_name})
    endif()

    add_test(${test_name} ${test_name})

    if(USE_VALGRIND)
        # TODO: This test has a deadlock when running on valgrind. Further investigation needed.
        string(COMPARE EQUAL ${test_name} NetworkStatusNotifierTest res)
        if(res)
            continue()
        endif()

        add_test(NAME memcheck_${test_name} COMMAND valgrind -q --leak-check=full --trace-children=yes $<TARGET_FILE:${test_name}>)
    endif()
endforeach()

if (ADDRESS_SANITIZER)
    # This test has a false positive when running under asan
    set_property(TEST "ConfigLoaderTest" PROPERTY ENVIRONMENT "ASAN_OPTIONS=detect_container_overflow=0")
endif()
```

--------------------------------

### Set Collector Log Level via API

Source: https://github.com/stackrox/collector/blob/master/docs/troubleshooting.md

An example of how to dynamically set the Collector's log level using a curl command. This allows for real-time adjustment of logging verbosity for debugging purposes.

```shell
$ curl -X POST -d "trace" collector:8080/loglevel
```

--------------------------------

### Get Network Connections with Filtering (Bash)

Source: https://github.com/stackrox/collector/blob/master/docs/troubleshooting.md

Retrieves network connection data from the collector's API. Supports filtering by container ID and disabling normalization. Requires a running collector instance.

```bash
$ curl "http://<collector>:8080/state/network/connection?container=c6f030bc4b42&normalize=false"
{
  "c6f030bc4b42" :
  [
    {
      "active" : true,
      "l4proto" : "TCP",
      "port" : 443,
      "to" : "10.96.0.1"
    }
  ]
}
```

--------------------------------

### Deploy Collector with Docker Compose

Source: https://context7.com/stackrox/collector/llms.txt

A configuration example for running the collector locally alongside a mock gRPC server. It requires privileged mode and specific host volume mounts to access system telemetry.

```yaml
version: "3.9"
services:
  collector:
    image: quay.io/stackrox-io/collector:<tag>
    container_name: collector-debug
    network_mode: host
    privileged: true
    environment:
      - GRPC_SERVER=localhost:9999
      - COLLECTOR_CONFIG={"logLevel":"debug","turnOffScrape":true,"scrapeInterval":2}
      - COLLECTION_METHOD=core-bpf
      - COLLECTOR_HOST_ROOT=/host
    volumes:
      - /var/run/docker.sock:/host/var/run/docker.sock:ro
      - /proc:/host/proc:ro
      - /etc:/host/etc:ro
      - /usr/lib:/host/usr/lib:ro
      - /sys/:/host/sys/:ro
      - /dev:/host/dev:ro
    depends_on:
      - grpc-server-debug
  grpc-server-debug:
    image: quay.io/rhacs-eng/grpc-server:latest
    container_name: grpc-server
    network_mode: host
    user: 1000:1000
    volumes:
      - /tmp:/tmp:rw
```

--------------------------------

### Checkout Release Branch for Patching (Shell)

Source: https://github.com/stackrox/collector/blob/master/docs/release.md

Navigates to the specific release branch (e.g., 'release-3.22') in the local repository. This is the starting point for applying patch releases.

```shell
git checkout release-"${COLLECTOR_RELEASE}"
```

--------------------------------

### GET /state/network/endpoint

Source: https://github.com/stackrox/collector/blob/master/docs/troubleshooting.md

Retrieves an array of all network endpoints currently known to the collector.

```APIDOC
## GET /state/network/endpoint

### Description
Returns an array of network endpoints known to the collector. Afterglow is not applied to this data.

### Method
GET

### Endpoint
/state/network/endpoint

### Parameters
#### Query Parameters
- **container** (string) - Optional - Filter results by a specific container_id.
- **normalize** (boolean) - Optional - Set to false to disable normalization of endpoints. Defaults to true.

### Response
#### Success Response (200)
- **endpoints** (array) - List of known network endpoints.
```

--------------------------------

### Install Ansible on macOS

Source: https://github.com/stackrox/collector/blob/master/ansible/README.md

Installs Ansible using Homebrew on macOS, as the default Python 3 version might be older than required. After installing Ansible, install the necessary dependencies using pip.

```bash
brew install ansible
pip3 install -r requirements.txt
```

--------------------------------

### Run Integration Tests with VM Management

Source: https://github.com/stackrox/collector/blob/master/ansible/README.md

The 'integration-tests.yml' playbook orchestrates the entire integration testing process, including VM creation, provisioning, test execution, and teardown. It supports tags for individual stages like 'setup', 'provision', 'run-tests', and 'teardown'.

```bash
VM_TYPE=rhel ansible-playbook -i dev integration-tests.yml
```

--------------------------------

### Install IBM Cloud Ansible Collection

Source: https://github.com/stackrox/collector/blob/master/ansible/README.md

Installs the 'ibm.cloudcollection' Ansible Galaxy collection, which is necessary for managing IBM Z and Power VMs through IBM Cloud.

```bash
ansible-galaxy collection install ibm.cloudcollection
```

--------------------------------

### Fetch Collector Profiling Data

Source: https://github.com/stackrox/collector/blob/master/docs/troubleshooting.md

Commands to retrieve heap or CPU profiles from the Collector service. The output can be processed using pprof for performance analysis.

```bash
curl collector:8080/profile/heap
curl collector:8080/profile/cpu
```

--------------------------------

### Retrieve Collector Pods and Logs using OC

Source: https://github.com/stackrox/collector/blob/master/docs/troubleshooting.md

Commands to list Collector pods and retrieve their logs using oc, which is compatible with kubectl. This method is an alternative for environments using OpenShift.

```shell
$ oc get pods -n stackrox -l app=collector
collector-vclg5                      1/2     CrashLoopBackOff   2 (25s ago)   2m41s

$ oc logs -n stackrox collector-vclg5 collector
$ oc logs -n stackrox collector-vclg5 collector --previous
```

--------------------------------

### Extract Container IDs from Kubernetes

Source: https://github.com/stackrox/collector/blob/master/docs/troubleshooting.md

A pipeline command to list all container IDs associated with the collector pods, formatted for use with the metadata endpoint.

```bash
kubectl -n stackrox get pods -l "app=collector" -o json \
    | jq -r '.items[].status.containerStatuses[].containerID' \
    | sed -e 's#containerd://##' \
    | cut -c -12
```

--------------------------------

### GET /state/*

Source: https://context7.com/stackrox/collector/llms.txt

Introspection endpoints to query the internal state of containers, network connections, and runtime configuration.

```APIDOC
## GET /state/containers/{id}

### Description
Retrieves metadata for a specific container by its short ID.

### Method
GET

### Endpoint
/state/containers/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The 12-character short container ID.

### Response
#### Success Response (200)
- **container_id** (string) - The ID of the container.
- **namespace** (string) - The namespace where the container resides.

### Response Example
{
  "container_id": "01e8c0454972",
  "namespace": "stackrox"
}
```

--------------------------------

### Configure Kubernetes Pod for GDB Debugging

Source: https://github.com/stackrox/collector/blob/master/docs/how-to-start.md

Defines the Kubernetes container specification to override the entrypoint with gdbserver. It includes the necessary environment variables for TLS configuration and exposes the debugging port.

```yaml
spec:
  template:
    spec:
      containers:
      - env:
        - name: COLLECTOR_CONFIG
          value: |
            '{"tlsConfig":{"caCertPath":"/var/run/secrets/stackrox.io/certs/ca.pem","clientCertPath":"/var/run/secrets/stackrox.io/certs/cert.pem","clientKeyPath":"/var/run/secrets/stackrox.io/certs/key.pem"}}'
      command:
      - gdbserver
      - 0.0.0.0:1337
      args:
      - collector
      image: quay.io/stackrox-io/collector:<your-built-tag-here>
      ports:
      - containerPort: 1337
        name: gdb
        protocol: TCP
```

--------------------------------

### Access Collector Introspection via Port-Forward

Source: https://github.com/stackrox/collector/blob/master/docs/troubleshooting.md

Expose the Collector introspection endpoints from a Kubernetes cluster to a local machine using kubectl port-forward.

```bash
kubectl -n stackrox port-forward ds/collector 8080:8080 &
```

--------------------------------

### Ansible Vault Encryption Example

Source: https://github.com/stackrox/collector/blob/master/ansible/README.md

Demonstrates how to encrypt a secrets.yml file using Ansible Vault for password protection. This requires adding the '--ask-vault-pass' flag to subsequent 'ansible-playbook' commands.

```bash
$ ansible-vault encrypt secrets.yml
```

--------------------------------

### Retrieve Collector Pods and Logs using Kubectl

Source: https://github.com/stackrox/collector/blob/master/docs/troubleshooting.md

Commands to list Collector pods and retrieve their logs using kubectl. This is useful for diagnosing issues by examining the Collector's output and error messages.

```shell
$ kubectl get pods -n stackrox -l app=collector
collector-vclg5                      1/2     CrashLoopBackOff   2 (25s ago)   2m41s

$ kubectl logs -n stackrox collector-vclg5 collector

# sometimes it is also useful to view the previous logs of collector,
# if the current restart is running
$ kubectl logs -n stackrox collector-vclg5 collector --previous
```

--------------------------------

### Connect to Remote GDB Session

Source: https://github.com/stackrox/collector/blob/master/docs/how-to-start.md

Commands to forward the container port to the local host and initiate a GDB session. It maps remote symbols to local source paths to enable effective debugging.

```bash
# Make the GDB port reachable from your host
kubectl -n stackrox port-forward ds/collector 40000:1337 &
# Connect to the remote GDB server and map collector symbols to your sources
gdb -ex "target extended-remote localhost:40000"\
    -ex "set substitute-path /tmp/collector /path/to/stackrox/collector"
```

--------------------------------

### Query Container Metadata via Collector API

Source: https://github.com/stackrox/collector/blob/master/docs/troubleshooting.md

Retrieve metadata for a specific container by its short ID. Requires the ROX_COLLECTOR_RUNTIME_CONFIG_ENABLED flag and CRI socket access.

```bash
curl collector:8080/state/containers/01e8c0454972
```

--------------------------------

### Configure VS Code Devcontainer

Source: https://github.com/stackrox/collector/blob/master/docs/how-to-start.md

Defines the development environment configuration for VS Code using the remote-containers extension. It specifies the base image required for the collector builder.

```json
{
  "name": "collector-dev",
  "image": "quay.io/stackrox-io/collector-builder:master"
}
```

--------------------------------

### Execute Ansible Integration Test Playbooks

Source: https://github.com/stackrox/collector/blob/master/ansible/README.md

Shell commands to trigger the integration test playbook. Includes examples for running a full lifecycle on a KinD cluster and executing tests on an existing cluster using tags.

```bash
# Run all tests on a throw-away KinD cluster
ansible-playbook \
    -i inventory.yml \
    -e '@k8s-tests.yml' \
    k8s-integration-tests.yml

# Run the tests on an existing cluster
ansible-playbook \
    -i inventory.yml \
    -e '@k8s-tests.yml' \
    --tags test-only \
    k8s-integration-tests.yml
```

--------------------------------

### Secrets.yml Structure Example

Source: https://github.com/stackrox/collector/blob/master/ansible/README.md

Defines the expected structure for the secrets.yml file, which should contain key-value pairs for credentials used by Ansible playbooks. Required credentials include quay_username and quay_password.

```yaml
---
quay_username: "<quay username>"
quay_password: "<quay_password>"
```

--------------------------------

### Build Debug-Enabled Collector Image

Source: https://github.com/stackrox/collector/blob/master/docs/how-to-start.md

Sets the CMake build type to Debug and triggers the make process to create a development image containing GDB for debugging purposes.

```bash
CMAKE_BUILD_TYPE=Debug make image-dev
```

--------------------------------

### Integrate Falco Security Libraries

Source: https://github.com/stackrox/collector/blob/master/collector/CMakeLists.txt

Configures the build to include external Falco libraries. It sets specific cache variables to disable unnecessary components like bundled dependencies and examples while enabling modern BPF support.

```cmake
set(FALCO_DIR ${PROJECT_SOURCE_DIR}/../falcosecurity-libs)

set(BUILD_DRIVER OFF CACHE BOOL "Build the driver on Linux" FORCE)
set(BUILD_LIBSCAP_MODERN_BPF ON CACHE BOOL "Enable modern bpf engine" FORCE)

add_subdirectory(${FALCO_DIR} falco)
```

--------------------------------

### Describe Collector Pod for Last State Information

Source: https://github.com/stackrox/collector/blob/master/docs/troubleshooting.md

Command to describe a Collector pod, focusing on its last terminated state. This helps in identifying the reason for a crash, such as specific error messages or exit codes.

```shell
# substitute your collector pod into this command
$ kubectl describe pod -n stackrox collector-vclg5
[...]
    Last State:     Terminated
      Reason:       Error
      Message:      No suitable kernel object downloaded
      Exit Code:    1
      Started:      Fri, 21 Oct 2022 11:50:56 +0100
      Finished:     Fri, 21 Oct 2022 11:51:25 +0100
[...]
```

--------------------------------

### Run Performance Containers

Source: https://github.com/stackrox/collector/blob/master/integration-tests/container/perf/README.md

Instructions for executing the initialization container to prepare the host environment and running specific tool containers with necessary volume mounts and privileges.

```bash
# running the init container
docker run --rm \
    -v /lib/modules:/host/lib/modules \
    -v /etc/os-release:/host/etc/os-release \
    -v /etc/lsb-release:/host/etc/lsb-release \
    -v /usr/src:/host/usr/src \
    quay.io/rhacs-eng/collector-performance:init

# running one of the tools containers
docker run --rm --privileged \
    -v /sys:/sys \
    -v /usr/src:/usr/src \
    -v /lib/modules:/lib/modules \
    -v /tmp:/tmp \
    quay.io/rhacs-eng/collector-performance:<tool> <tool args>
```

--------------------------------

### Run performance benchmarks with profiling tools

Source: https://github.com/stackrox/collector/blob/master/integration-tests/README.md

Configures performance measurement tools like bpftrace, BCC, and perf by setting specific environment variables before executing make commands. These tools run in isolated containers to profile the collector under load.

```bash
# Capture the count of all syscalls executed during the benchmark baseline
COLLECTOR_BPFTRACE_COMMAND="-e 'tracepoint:raw_syscalls:sys_enter { @syscalls = count(); }'" make baseline

# Run the collector-syscall-count tool
COLLECTOR_BPFTRACE_COMMAND='/tools/collector-syscalls-count.bt' make benchmark

# Run the syscount BCC tool, measuring syscall latency
COLLECTOR_BCC_COMMAND='syscount --latency' make benchmark

# Record perf events, writing /tmp
COLLECTOR_PERF_COMMAND='record -o /tmp/perf.data' make benchmark
```

--------------------------------

### Build and Push Performance Images

Source: https://github.com/stackrox/collector/blob/master/integration-tests/container/perf/README.md

Commands to build and push all performance measurement Docker images using the project's Makefile.

```bash
# build all images
make all

# push all images
make push
```

--------------------------------

### Build Collector natively with vcpkg

Source: https://context7.com/stackrox/collector/llms.txt

Instructions for setting up the build environment and compiling the collector natively on a Linux host. It uses CMake presets and vcpkg for dependency management.

```bash
dnf install -y gcc clang make cmake zip unzip tar autoconf automake libtool kernel-devel perl libbpf-devel bpftool libcap-ng-devel libuuid-devel
cmake --preset=vcpkg
cmake --build cmake-build/vcpkg -j$(nproc)
ctest --test-dir cmake-build/vcpkg
```

--------------------------------

### POST /profile/{type}

Source: https://context7.com/stackrox/collector/llms.txt

Manage CPU and heap profiling for performance analysis.

```APIDOC
## POST /profile/{type}

### Description
Starts or stops profiling for the specified type (cpu or heap).

### Method
POST

### Endpoint
/profile/{type}

### Parameters
#### Path Parameters
- **type** (string) - Required - The profile type: "cpu" or "heap".

### Request Body
- **action** (string) - Required - "on" to start, "off" to stop.

### Request Example
"on"

### Response
#### Success Response (200)
- **status** (string) - Confirmation of the profiling state change.
```

--------------------------------

### Configure Protobuf and gRPC generation in CMake

Source: https://github.com/stackrox/collector/blob/master/collector/proto/CMakeLists.txt

This script locates necessary dependencies, defines the Protobuf source files, and configures the build targets to generate C++ headers and source files. It specifically enables mock code generation for gRPC services to facilitate testing.

```cmake
find_package(protobuf CONFIG REQUIRED)
find_package(gRPC CONFIG REQUIRED)
find_package(Threads)

set(ROX_PROTO_FILES
    api/v1/empty.proto
    api/v1/signal.proto
    internalapi/sensor/collector.proto
    internalapi/sensor/network_connection_info.proto
    internalapi/sensor/network_connection_iservice.proto
    internalapi/sensor/network_enums.proto
    internalapi/sensor/signal_iservice.proto
    storage/network_flow.proto
    storage/process_indicator.proto
)

add_library(rox-proto ${ROX_PROTO_FILES})
target_link_libraries(rox-proto
    PUBLIC
    protobuf::libprotobuf
    gRPC::grpc
    gRPC::grpc++
)
target_include_directories(rox-proto PUBLIC ${CMAKE_CURRENT_BINARY_DIR})

get_target_property(grpc_cpp_plugin_location gRPC::grpc_cpp_plugin LOCATION)
protobuf_generate(TARGET rox-proto LANGUAGE cpp)
protobuf_generate(TARGET rox-proto LANGUAGE grpc GENERATE_EXTENSIONS .grpc.pb.h .grpc.pb.cc PLUGIN "protoc-gen-grpc=${grpc_cpp_plugin_location}" PLUGIN_OPTIONS generate_mock_code=true)
```

--------------------------------

### Build StackRox Collector container images

Source: https://context7.com/stackrox/collector/llms.txt

Commands to build production and development container images for the collector using the project Makefile. This process compiles necessary dependencies including gRPC and Falco libraries.

```bash
git clone --recurse-submodules https://github.com/stackrox/collector.git
cd collector
make image
CMAKE_BUILD_TYPE=Debug make image-dev
```

--------------------------------

### Automate Collector Release with release.py

Source: https://github.com/stackrox/collector/blob/master/utilities/docs/release.md

This script automates the creation of release branches or tags for the collector project. It requires major and minor version arguments and supports an optional --push flag to sync changes with the remote repository.

```bash
./release.py M.m
```

--------------------------------

### Basic Collector DaemonSet Deployment (Kubernetes YAML)

Source: https://context7.com/stackrox/collector/llms.txt

A basic DaemonSet configuration for deploying the StackRox collector to a Kubernetes cluster. It specifies necessary volume mounts for accessing host system information and sets essential environment variables for collector operation.

```yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: collector
  namespace: stackrox
spec:
  selector:
    matchLabels:
      app: collector
  template:
    metadata:
      labels:
        app: collector
    spec:
      containers:
      - name: collector
        image: quay.io/stackrox-io/collector:latest
        env:
        - name: GRPC_SERVER
          value: "sensor.stackrox.svc:9998"
        - name: COLLECTION_METHOD
          value: "core-bpf"
        - name: COLLECTOR_HOST_ROOT
          value: "/host"
        - name: COLLECTOR_CONFIG
          value: '{"logLevel":"info","scrapeInterval":30}'
        securityContext:
          privileged: true
        volumeMounts:
        - mountPath: /host/var/run/docker.sock
          name: docker-sock
          readOnly: true
        - mountPath: /host/proc
          name: proc
          readOnly: true
        - mountPath: /host/etc
          name: etc
          readOnly: true
        - mountPath: /host/sys
          name: sys
          readOnly: true
        - mountPath: /host/dev
          name: dev
          readOnly: true
        ports:
        - containerPort: 8080
          name: api
        - containerPort: 9090
          name: metrics
      volumes:
      - name: docker-sock
        hostPath:
          path: /var/run/docker.sock
      - name: proc
        hostPath:
          path: /proc
      - name: etc
        hostPath:
          path: /etc
      - name: sys
        hostPath:
          path: /sys
      - name: dev
        hostPath:
          path: /dev
```

--------------------------------

### Enable Container Runtime Integration (Kubernetes YAML)

Source: https://context7.com/stackrox/collector/llms.txt

Configuration to enable the collector's integration with container runtimes like containerd and CRI-O. This involves setting an environment variable and mounting the respective runtime sockets. It also includes bash commands to retrieve container IDs and query metadata.

```yaml
spec:
  template:
    spec:
      containers:
      - name: collector
        env:
        - name: ROX_COLLECTOR_RUNTIME_CONFIG_ENABLED
          value: "true"
        volumeMounts:
        - mountPath: /host/run/containerd/containerd.sock
          mountPropagation: HostToContainer
          name: containerd-sock
        - mountPath: /host/run/crio/crio.sock
          mountPropagation: HostToContainer
          name: crio-sock
      volumes:
      - hostPath:
          path: /run/containerd/containerd.sock
        name: containerd-sock
      - hostPath:
          path: /run/crio/crio.sock
        name: crio-sock
```

```bash
# Get container IDs for querying
kubectl -n stackrox get pods -l "app=collector" -o json \
    | jq -r '.items[].status.containerStatuses[].containerID' \
    | sed -e 's#containerd://##' \
    | cut -c -12

# Query container metadata
curl "localhost:8080/state/containers/01e8c0454972"
```

--------------------------------

### Create and Push Internal Release Tag (Shell)

Source: https://github.com/stackrox/collector/blob/master/docs/release.md

Creates an internal release tag on the master branch to mark the point from which the release is forked. This tag is then pushed to the origin.

```shell
git tag "${COLLECTOR_RELEASE}.x"
git push origin "${COLLECTOR_RELEASE}.x"
```

--------------------------------

### Configure CMake Build Environment for Collector

Source: https://github.com/stackrox/collector/blob/master/collector/CMakeLists.txt

This snippet demonstrates the initialization of the CMake build system, including finding required packages, setting C++ compiler flags, and configuring sanitizers for debugging and testing.

```cmake
find_package(Threads)
find_package(CURL REQUIRED)
find_package(yaml-cpp REQUIRED)
find_package(gRPC CONFIG REQUIRED)
find_package(civetweb CONFIG REQUIRED)
find_package(prometheus-cpp CONFIG REQUIRED)

set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fPIC -Wall --std=c++17 -pthread -Wno-deprecated-declarations -fno-omit-frame-pointer -rdynamic")

if(ADDRESS_SANITIZER)
	set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fsanitize=address -fsanitize=undefined -DGRPC_ASAN_SUPPRESSED")
endif()
```

--------------------------------

### Debug Playbook Execution with Step Mode

Source: https://github.com/stackrox/collector/blob/master/ansible/README.md

Runs an Ansible playbook in step-by-step mode, prompting the user for confirmation before executing each task. This is useful for identifying failures or verifying task behavior during development.

```bash
ansible-playbook \
    -i inventory.yml \
    -e '@k8s-tests.yml' \
    --step \
    k8s-integration-tests.yml
```

--------------------------------

### Checkout and Pull Master Branch (Shell)

Source: https://github.com/stackrox/collector/blob/master/docs/release.md

Ensures the local repository is on the master branch and up-to-date with the remote repository. This is a prerequisite for manual release processes.

```shell
git checkout master
git pull
```

--------------------------------

### Tag and Push Release Version (Shell)

Source: https://github.com/stackrox/collector/blob/master/docs/release.md

Tags the current commit with the specified release version (e.g., '3.22.0') and pushes the tag to the origin repository. This marks the official release point.

```shell
git tag "${COLLECTOR_RELEASE}.${COLLECTOR_PATCH_NUMBER}"
git push origin "${COLLECTOR_RELEASE}.${COLLECTOR_PATCH_NUMBER}"
```

--------------------------------

### View Collector Logs (Kubernetes Bash)

Source: https://context7.com/stackrox/collector/llms.txt

Commands to view logs for the StackRox collector pods in Kubernetes. This includes fetching the collector pod name, viewing current logs, retrieving logs from a previous container instance (after a crash), and describing the pod for termination messages.

```bash
# Get collector pod name
kubectl get pods -n stackrox -l app=collector
# Output: collector-vclg5   1/2   Running   0   2m41s

# View current logs
kubectl logs -n stackrox collector-vclg5 collector

# View previous container logs (after crash)
kubectl logs -n stackrox collector-vclg5 collector --previous

# Check pod status for termination message
kubectl describe pod -n stackrox collector-vclg5
# Look for:
#   Last State:     Terminated
#   Message:      No suitable kernel object downloaded
```

--------------------------------

### Control CPU Profiling and Download Profiles (curl)

Source: https://context7.com/stackrox/collector/llms.txt

Commands to interact with the collector's CPU profiling endpoint. This allows stopping profiling, downloading the profile data, and then analyzing it using the pprof tool. Ensure you have debugging symbols for accurate analysis.

```bash
curl -X POST -d "off" http://collector:8080/profile/cpu

curl http://collector:8080/profile/cpu > cpu.prof

pprof --text ./collector heap.prof
```

--------------------------------

### Update and Tag Falcosecurity-libs Submodule (Shell)

Source: https://github.com/stackrox/collector/blob/master/docs/release.md

Updates the falcosecurity-libs submodule, tags it with the current release version, and pushes the tag. This ensures the collector uses the correct version of its dependencies.

```shell
git submodule update --init falcosecurity-libs
cd falcosecurity-libs
git tag "${COLLECTOR_RELEASE}.${COLLECTOR_PATCH_NUMBER}"
git push origin "${COLLECTOR_RELEASE}.${COLLECTOR_PATCH_NUMBER}"
```

--------------------------------

### Collector Runtime Configuration YAML

Source: https://context7.com/stackrox/collector/llms.txt

Dynamically configure the collector using a YAML file, which can be updated without restarting the collector. This supports settings for networking features like external IPs and connection limits.

```yaml
# /etc/stackrox/runtime_config.yaml (or ConfigMap)
networking:
  externalIps:
    enabled: ENABLED           # ENABLED or DISABLED
    direction: BOTH            # INGRESS, EGRESS, or BOTH
  maxConnectionsPerMinute: 2048
```

```yaml
# Kubernetes ConfigMap example
apiVersion: v1
kind: ConfigMap
metadata:
  name: collector-config
  namespace: stackrox
data:
  runtime_config.yaml: |
    networking:
      externalIps:
        enabled: ENABLED
        direction: EGRESS
      maxConnectionsPerMinute: 1234
```

--------------------------------

### Configure Collector environment variables

Source: https://context7.com/stackrox/collector/llms.txt

Common environment variables used to tune collector behavior, including collection methods, network filtering, and performance buffer settings.

```bash
COLLECTION_METHOD=core-bpf
GRPC_SERVER=sensor.stackrox.svc:9998
ROX_COLLECTOR_LOG_LEVEL=INFO
ROX_IGNORE_NETWORKS=169.254.0.0/16,fe80::/10
ROX_COLLECTOR_SINSP_BUFFER_SIZE=8388608
```

--------------------------------

### Build and Push Builder Image (CI)

Source: https://github.com/stackrox/collector/blob/master/ansible/README.md

The 'ci-build-builder.yml' playbook is used in CI environments to build the collector builder image, retag it, and push it to quay.io. It utilizes environment variables for tagging and platform specification.

```yaml
# ci-build-builder.yml playbook execution example (not actual code)
# Environment variables like COLLECTOR_BUILDER_TAG and PLATFORM would be set before running.
```

--------------------------------

### Collector Debugging Configuration and Connection (Kubernetes YAML & Bash)

Source: https://context7.com/stackrox/collector/llms.txt

Configuration to enable remote debugging for the collector in Kubernetes. This involves patching the DaemonSet to expose a GDB server port, building a debug image, port-forwarding the GDB port, and connecting with GDB. Requires a debug image tag and local path to collector source.

```yaml
# Patch the collector DaemonSet for debugging
spec:
  template:
    spec:
      containers:
      - name: collector
        env:
        - name: COLLECTOR_CONFIG
          value: |
            '{"tlsConfig":{"caCertPath":"/var/run/secrets/stackrox.io/certs/ca.pem","clientCertPath":"/var/run/secrets/stackrox.io/certs/cert.pem","clientKeyPath":"/var/run/secrets/stackrox.io/certs/key.pem"}}'
        command:
        - gdbserver
        - 0.0.0.0:1337
        args:
        - collector
        image: quay.io/stackrox-io/collector:<debug-tag>
        ports:
        - containerPort: 1337
          name: gdb
          protocol: TCP
```

```bash
# Build debug image
CMAKE_BUILD_TYPE=Debug make image-dev

# Port-forward GDB port
kubectl -n stackrox port-forward ds/collector 40000:1337 &

# Connect with GDB
gdb -ex "target extended-remote localhost:40000" \
    -ex "set substitute-path /tmp/collector /path/to/collector"
```

--------------------------------

### Analyze Kubernetes JSON logs with jq

Source: https://github.com/stackrox/collector/blob/master/integration-tests/README.md

Uses jq to filter and extract specific data points from bulky JSON and JSONL log files generated during Kubernetes testing. This allows for easier inspection of container configurations and pod-specific events.

```bash
# Get the container configuration from a pod
jq '.spec.containers[]' TestK8sNamespace-collector-tests-collector-config.json

# Get all events from the collector pod
jq 'select(.involvedObject.name == "collector")' core-bpf/TestK8sNamespace-collector-tests-events.jsonl
```

--------------------------------

### Collector Profiling HTTP API

Source: https://context7.com/stackrox/collector/llms.txt

Utilize gperftools integration to profile CPU and memory usage of the collector. This allows enabling, disabling, and downloading heap and CPU profiles for performance analysis.

```bash
# Enable heap profiling
curl -X POST -d "on" http://collector:8080/profile/heap

# Wait for profiling data to accumulate
sleep 60

# Stop heap profiling
curl -X POST -d "off" http://collector:8080/profile/heap

# Download heap profile
curl http://collector:8080/profile/heap > heap.prof

# Enable CPU profiling
curl -X POST -d "on" http://collector:8080/profile/cpu
```

--------------------------------

### Tag and Push Patch Release (Shell)

Source: https://github.com/stackrox/collector/blob/master/docs/release.md

Tags the current commit with the patch version (e.g., '3.22.1') and pushes the tag along with any preceding commits. This is used for releasing patch updates.

```shell
git tag "${COLLECTOR_RELEASE}.${COLLECTOR_PATCH_NUMBER}"
git push --follow-tags
```

--------------------------------

### Run Collector in standalone mode

Source: https://context7.com/stackrox/collector/llms.txt

Methods to execute the collector without a gRPC server, forcing it to output telemetry events as JSON to standard output. This is useful for debugging and local event inspection.

```bash
docker run --privileged \
  -e GRPC_SERVER= \
  -e COLLECTION_METHOD=core-bpf \
  -v /proc:/host/proc:ro \
  quay.io/stackrox-io/collector:<tag>

collector --grpc-server=
```

--------------------------------

### Configure Ansible Variables for Integration Tests

Source: https://github.com/stackrox/collector/blob/master/ansible/README.md

A template YAML file for defining required variables such as image names and repository paths. This file is passed to the ansible-playbook command using the -e flag.

```yaml
---
tester_image: <tester image>
collector_image: <collector image>
collector_root: <path to the collector repo>
cluster_name: collector-tests
```

--------------------------------

### Configure CMake Project for Collector

Source: https://github.com/stackrox/collector/blob/master/CMakeLists.txt

Sets the minimum required CMake version and initializes the project. It also enables testing and includes the collector subdirectory for build processing.

```cmake
cmake_minimum_required(VERSION 3.15)
project(collector)

enable_testing()

add_subdirectory(collector)
```

--------------------------------

### Create Release Branch and Modify Tekton Config (Shell)

Source: https://github.com/stackrox/collector/blob/master/docs/release.md

Creates a new release branch and modifies the .tekton/collector-build.yaml file to include the ACS version suffix. This prepares the build configuration for the new release.

```shell
git checkout -b "release-${COLLECTOR_RELEASE}"
sed -i \
    -e "/appstudio.openshift.io\/application: / s/$/-${STACKROX_SUFFIX}/" \
    -e "/appstudio.openshift.io\/component: / s/$/-${STACKROX_SUFFIX}/" \
    -e "/serviceAccountName: / s/$/-${STACKROX_SUFFIX}/" \
    .tekton/collector-build.yaml
git commit -m "Empty commit to diverge ${COLLECTOR_RELEASE} from master"
git push --set-upstream origin "release-${COLLECTOR_RELEASE}"
```

--------------------------------

### POST /loglevel

Source: https://context7.com/stackrox/collector/llms.txt

Dynamically update the logging level of the collector at runtime without requiring a service restart.

```APIDOC
## POST /loglevel

### Description
Updates the active log level for the collector process.

### Method
POST

### Endpoint
/loglevel

### Request Body
- **level** (string) - Required - The desired log level. Available values: trace, debug, info, warning, error, fatal.

### Request Example
"debug"

### Response
#### Success Response (200)
- **status** (string) - Confirmation of the updated log level.

### Response Example
"Log level set to debug"
```

--------------------------------

### Build and Push Collector Image (CI)

Source: https://github.com/stackrox/collector/blob/master/ansible/README.md

The 'ci-build-collector.yml' playbook is designed for CI to handle the retagging and pushing of Collector images to quay.io. It uses environment variables for builder image tags, platform, collector tags, and registry specifics.

```yaml
# ci-build-collector.yml playbook execution example (not actual code)
# Environment variables like COLLECTOR_BUILDER_TAG, PLATFORM, COLLECTOR_TAG, and RHACS_ENG_IMAGE would be set.
```

--------------------------------

### Collector JSON Configuration

Source: https://context7.com/stackrox/collector/llms.txt

Configure the collector using a JSON file or environment variable. This allows setting parameters like log level, scrape interval, and disabling scraping. The `tlsConfig` section can specify paths for CA certificates and client credentials.

```bash
# Set collector configuration via environment variable
export COLLECTOR_CONFIG='{"logLevel":"debug","scrapeInterval":15,"turnOffScrape":false}'

# Or via command line
collector --collector-config='{"logLevel":"info","scrapeInterval":30}'
```

```json
{
  "logLevel": "INFO",
  "scrapeInterval": 30,
  "turnOffScrape": false,
  "tlsConfig": {
    "caCertPath": "/var/run/secrets/stackrox.io/certs/ca.pem",
    "clientCertPath": "/var/run/secrets/stackrox.io/certs/cert.pem",
    "clientKeyPath": "/var/run/secrets/stackrox.io/certs/key.pem"
  }
}
```

--------------------------------

### Cleanup Cluster Resources with Ansible

Source: https://github.com/stackrox/collector/blob/master/ansible/README.md

Executes the cleanup tag within an Ansible playbook to remove objects created during integration tests. This command requires an inventory file and specific environment variables defined in the configuration.

```bash
ansible-playbook \
    -i inventory.yml \
    -e '@k8s-tests.yml' \
    --tags cleanup \
    k8s-integration-tests.yml
```

--------------------------------

### Define Collector ConfigMap for Kubernetes

Source: https://github.com/stackrox/collector/blob/master/docs/references.md

A Kubernetes ConfigMap manifest used to inject runtime configuration into the StackRox Collector. The configuration is stored under the 'runtime_config.yaml' key within the data section.

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: collector-config
  namespace: stackrox
data:
  runtime_config.yaml: |
    networking:
      externalIps:
        enabled: ENABLED
      maxConnectionsPerMinute: 1234
```

--------------------------------

### Define Ansible Inventory for Local Kubernetes Execution

Source: https://github.com/stackrox/collector/blob/master/ansible/README.md

A standard Ansible inventory configuration for running tests against a local kubeconfig environment. It sets the connection to local and specifies the Python interpreter.

```yaml
all:
  hosts:
    local:
      ansible_connection: local
      ansible_python_interpreter: "{{ansible_playbook_python}}"
```

--------------------------------

### Collector Prometheus Metrics HTTP API

Source: https://context7.com/stackrox/collector/llms.txt

Expose performance metrics and statistics via the Prometheus endpoint. This allows for monitoring of network scraping, event counts, connection statistics, and more.

```bash
# Fetch all metrics
curl http://collector:9090/metrics

# Example output includes:
# rox_collector_timers - Network scraping timers
# rox_collector_counters - Event counters
# rox_collector_events - System inspector counters
# rox_connections_total - Connection statistics
# rox_connections_rate - Connection creation rate
```

```prometheus
# HELP rox_connections_total Amount of stored connections over time
# TYPE rox_connections_total summary
rox_connections_total{dir="out",peer="private",quantile="0.5"} 1558
rox_connections_total{dir="out",peer="private",quantile="0.9"} 2067
rox_connections_total{dir="in",peer="private",quantile="0.5"} 101

# HELP rox_collector_events_typed Per-syscall timing metrics
rox_collector_event_times_us_total{event_dir="<",event_type="accept",step="process"} 45994
rox_collector_event_times_us_avg{event_dir="<",event_type="accept",step="process"} 3
```

--------------------------------

### Collector Log Level HTTP API

Source: https://context7.com/stackrox/collector/llms.txt

Dynamically change the collector's log level at runtime using HTTP POST requests. This is useful for debugging and troubleshooting without requiring a restart. Available levels include trace, debug, info, warning, error, and fatal.

```bash
# Set log level to trace for debugging
curl -X POST -d "trace" http://collector:8080/loglevel

# Set log level to debug
curl -X POST -d "debug" http://collector:8080/loglevel

# Set log level back to info
curl -X POST -d "info" http://collector:8080/loglevel

# Available levels: trace, debug, info, warning, error, fatal
```
Tokens:
Raw