# BlueRock Sandbox Observability The BlueRock Sandbox logs execution events and system activity to a local file. Reviewing these logs provides immediate visibility into authorized and unauthorized application behavior. ### Specifying the Log File By default, the sandbox writes all activity to a file named `BRace.log` (or `sandbox.log` depending on the alias) in the current working directory. To specify a custom location or filename, use the `-l` or `--logfile` parameter during execution. {% code overflow="wrap" %} ```shellscript $ brace -l ./mylogs.log -v /usr:/usr -v /lib:/lib -v /lib64:/lib64 -v /dev:/dev -v /home/ubuntu:/home/ubuntu --name sandbox_exec -- /usr/bin/bash ``` {% endcode %} To stream logs directly to the terminal for real-time observation, specify `stdout`: {% code overflow="wrap" %} ```shellscript $ brace -l stdout -v /usr:/usr -v /lib:/lib -v /lib64:/lib64 -v /dev:/dev -v /home/ubuntu:/home/ubuntu --name sandbox_exec -- /usr/bin/bash ``` {% endcode %} Expected output: {% code overflow="wrap" lineNumbers="true" %} ```shellscript 2026-04-02T09:19:00.088321982Z INFO main acoustic::connector: acoustic/src/connector.rs:33: Using socket paths: "/run/bluerock/sensor.sock", None, None 2026-04-02T09:19:00.089577704Z INFO main libgyro: /builds/bedrocksystems/bru/uc/services/libgyro/src/lib.rs:60: Creating libgyro engine with the following config: { "rules": { "brace/exec": { "enabled": true, "content": "", "used_events": null } }, "data": { "bluerock": { "brace": { "config": { "exec": { "remediate": true, "explicit_deny_list": true, "match_list": [ "/usr/bin/date", "/usr/bin/whoami", "/usr/bin/uptime" ] } } } } } } 2026-04-02T09:19:00.089761773Z INFO main brace::runtime::common::opts: brace/src/runtime/common/opts.rs:126: Final opts after CLI overrides - user: None, pid_ns: true, user_ns: false, bind_mount: true allow privileged: true 2026-04-02T09:19:00.090386678Z INFO main brace: brace/src/main.rs:674: Test: child pid=298632 2026-04-02T09:19:00.090812Z WARN main brace: brace/src/main.rs:738: Running in ROOTLESS mode: Capabilities are namespaced. CAP_NET_RAW will NOT work for raw sockets (ping will fail). 2026-04-02T09:19:00.091287125Z INFO main brace::capability: brace/src/capability.rs:127: Ambient capabilities (will survive exec): [CAP_SYS_ADMIN, CAP_NET_RAW] 2026-04-02T09:19:00.092571742Z INFO main brace::capability: brace/src/capability.rs:174: Dropped CAP_SYS_ADMIN capability after mount operations 2026-04-02T09:19:00.092592104Z INFO main brace::capability: brace/src/capability.rs:199: Dropped temporal capabilities: network=false, mount=true, setuid=false ``` {% endcode %} ### Viewing Sandbox Logs Standard Linux utilities can be used to monitor and review the generated log files. To view the entire log file: {% code overflow="wrap" %} ```shellscript $ cat mylogs_rCURRENT.log ``` {% endcode %} Example output: {% code overflow="wrap" lineNumbers="true" %} ```shellscript 2026-04-02T09:23:36.486612583Z INFO main acoustic::connector: acoustic/src/connector.rs:33: Using socket paths: "/run/bluerock/sensor.sock", None, None 2026-04-02T09:23:36.488003175Z INFO main libgyro: /builds/bedrocksystems/bru/uc/services/libgyro/src/lib.rs:60: Creating libgyro engine with the following config: { "rules": { "brace/exec": { "enabled": true, "content": "", "used_events": null } }, "data": { "bluerock": { "brace": { "config": { "exec": { "remediate": true, "explicit_deny_list": true, "match_list": [ "/usr/bin/date", "/usr/bin/whoami", "/usr/bin/uptime" ] } } } } } } 2026-04-02T09:23:36.488161758Z INFO main brace::runtime::common::opts: brace/src/runtime/common/opts.rs:126: Final opts after CLI overrides - user: None, pid_ns: true, user_ns: false, bind_mount: true allow privileged: true 2026-04-02T09:23:36.488753734Z INFO main brace: brace/src/main.rs:674: Test: child pid=298733 2026-04-02T09:23:36.489131562Z WARN main brace: brace/src/main.rs:738: Running in ROOTLESS mode: Capabilities are namespaced. CAP_NET_RAW will NOT work for raw sockets (ping will fail). 2026-04-02T09:23:36.489612448Z INFO main brace::capability: brace/src/capability.rs:127: Ambient capabilities (will survive exec): [CAP_NET_RAW, CAP_SYS_ADMIN] 2026-04-02T09:23:36.490707466Z INFO main brace::capability: brace/src/capability.rs:174: Dropped CAP_SYS_ADMIN capability after mount operations 2026-04-02T09:23:36.49072594Z INFO main brace::capability: brace/src/capability.rs:199: Dropped temporal capabilities: network=false, mount=true, setuid=false ``` {% endcode %} To monitor logs in real-time (follow mode): ```shellscript $ tail -f mylogs_rCURRENT.log ``` Expected output: {% code overflow="wrap" lineNumbers="true" %} ```shellscript } } } 2026-04-02T09:23:36.488161758Z INFO main brace::runtime::common::opts: brace/src/runtime/common/opts.rs:126: Final opts after CLI overrides - user: None, pid_ns: true, user_ns: false, bind_mount: true allow privileged: true 2026-04-02T09:23:36.488753734Z INFO main brace: brace/src/main.rs:674: Test: child pid=298733 2026-04-02T09:23:36.489131562Z WARN main brace: brace/src/main.rs:738: Running in ROOTLESS mode: Capabilities are namespaced. CAP_NET_RAW will NOT work for raw sockets (ping will fail). 2026-04-02T09:23:36.489612448Z INFO main brace::capability: brace/src/capability.rs:127: Ambient capabilities (will survive exec): [CAP_NET_RAW, CAP_SYS_ADMIN] 2026-04-02T09:23:36.490707466Z INFO main brace::capability: brace/src/capability.rs:174: Dropped CAP_SYS_ADMIN capability after mount operations 2026-04-02T09:23:36.49072594Z INFO main brace::capability: brace/src/capability.rs:199: Dropped temporal capabilities: network=false, mount=true, setuid=false ``` {% endcode %} {% hint style="info" icon="notes-sticky" %} **Note:** BlueRock Sandbox always creates a log file with `_rCURRENT.log` that always capture the current actions/logs happening in the sandbox. By default `BRace_rCURRENT.log` is present that monitors all the current logs. {% endhint %} ### Understanding Log Entries Log entries are time-stamped and indicate whether an execution attempt was permitted or blocked based on the configured policy. Example `remediate: false`: Observe mode when execution is permitted with `remediate: false` is set, the log records a warning but allows the process to continue. {% code overflow="wrap" %} ```shellscript 2026-03-10T09:49:58.074Z INFO brace exec: process '/usr/bin/bash' (10817) tried to execute '/usr/bin/date' [Action: Logged] ``` {% endcode %} Example `remediate: true`: Enforcement mode when execution is blocked with `remediate: true` is set, the log records an error and indicates the process was stopped. {% code overflow="wrap" %} ```shellscript 2026-03-10T10:05:38.312Z ERROR brace exec: process '/usr/bin/bash' (12134) tried to execute '/usr/bin/date' [Action: Blocked] ``` {% endcode %} ### OpenTelemetry (OTEL) Event Collection The BlueRock Sandbox (`brace`) integrates with a local OTEL collector to export runtime telemetry, execution events, and policy violations (e.g., blocked execution attempts). When a sandbox is launched, events are routed through the BlueRock sensor socket to the local OTEL collector. 1. **Verify Local OTEL Services**\ Before running the sandbox, ensure the OTEL Collector and BlueRock control plane are actively running on the host node. ```shellscript $ sudo docker ps ``` Expected output: ```shellscript CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 847017b20665 ultracontrol:latest "/opt/bluerock/sbin/…" 3 days ago Up 3 days uc 8af1e7fb371f us-docker.pkg.dev/cloud-ops-agents-artifacts/google-cloud-opentelemetry-collector/otelcol-google:0.141.0 "/otelcol-google --f…" 4 weeks ago Up 4 weeks 0.0.0.0:4317-4318->4317-4318/tcp, [::]:4317-4318->4317-4318/tcp otel-collector ``` 2. **Trigger Sandbox Telemetry**\ Run a sandboxed application to generate runtime telemetry. For example, [executing the MCP file server](/bluerock-sandbox/bluerock-sandbox.md#running-python-mcp-server-and-mcp-client-programs) with the required BlueRock bind mounts will automatically stream startup and runtime events to the collector. 3. **View Sandbox Events in the Local Collector**\ Check the local OTEL collector logs to verify that the sandbox execution events were successfully received and processed. ```shellscript $ sudo docker logs otel-collector ``` Expected output: ```shellscript 2026-03-25T09:14:13.346Z info memorylimiter@v0.141.0/memorylimiter.go:146 Using percentage memory limiter {"resource": {"service.instance.id": "1cdf009f-b51a-4073-bc25-505728924255", "service.name": "otelcol-google", "service.version": "0.141.0"}, "otelcol.component.kind": "processor", "total_memory_mib": 15995, "limit_percentage": 65, "spike_limit_percentage": 20} 2026-03-25T09:14:13.347Z info memorylimiter@v0.141.0/memorylimiter.go:71 Memory limiter configured {"resource": {"service.instance.id": "1cdf009f-b51a-4073-bc25-505728924255", "service.name": "otelcol-google", "service.version": "0.141.0"}, "otelcol.component.kind": "processor", "limit_mib": 10396, "spike_limit_mib": 3199, "check_interval": 1} 2026-03-25T09:14:13.348Z info service@v0.141.0/service.go:224 Starting otelcol-google... {"resource": {"service.instance.id": "1cdf009f-b51a-4073-bc25-505728924255", "service.name": "otelcol-google", "service.version": "0.141.0"}, "Version": "0.141.0", "NumCPU": 4} 2026-03-25T09:14:13.348Z info extensions/extensions.go:40 Starting extensions... {"resource": {"service.instance.id": "1cdf009f-b51a-4073-bc25-505728924255", "service.name": "otelcol-google", "service.version": "0.141.0"}} ``` *** ### Advanced OpenTelemetry (OTEL) Event Routing #### **Understanding the OTEL Data Flow** Standard sandbox execution logs reside locally in `BRace_rCURRENT.log`. The OpenTelemetry (OTEL) Collector does not store execution events locally. The local `otel-collector` container acts as a telemetry pipeline. The pipeline receives raw data from the BlueRock sensor, enriches the data with cloud provider metadata, and immediately exports the data to a centralized cloud observability platform. Checking `docker logs otel-collector` only displays internal service logs, such as startup events and memory limiter configurations. Viewing actual sandbox policy violations and execution traces requires querying the configured export destination or enabling local debugging. *** ### **Viewing OTEL Events** The OTEL Collector exports telemetry data directly to the centralized observability platform of the active cloud provider. Select the relevant deployment environment below for specific querying instructions: * [Viewing Events in Google Cloud Platform (GCP)](#viewing-events-in-google-cloud-platform-gcp): Instructions for filtering and viewing BlueRock telemetry using the GCP Logs Explorer. * [Viewing Events in Amazon Web Service (AWS)](https://www.google.com/search?q=%23viewing-events-in-amazon-web-service-aws): Instructions for filtering and viewing BlueRock telemetry using AWS CloudWatch Log Management. #### **Viewing Events in Google Cloud Platform (GCP)** During GCP deployments, the BlueRock OTEL collector uses the `googlecloud` exporter defined in `/opt/bluerock/otel/otel-config.yaml`. * Destination: Google Cloud Logging * Enrichment: The `resourcedetection` processor automatically tags events with the corresponding GCP Project ID, Zone, and Instance Name. Querying the Logs in GCP: 1. Access the Google Cloud Console. 2. Navigate to **Logging** > **Logs Explorer**.\ ![](/files/VaYURmdYs5z7CD2aClOJ) 3. Ensure the active project selected in the top navigation bar matches the deployment environment. 4. By default, the Logs Explorer displays events for All log names. To filter exclusively for BlueRock telemetry, locate the LQL (Logging query language) text box.\ ![](/files/mqASA2ZgTOOFxKzkK3Ui) 5. Enter the following query string, replacing the placeholder with the actual project ID: 
logName="projects/[PROJECT_ID]/logs/bluerock"
6. Click **Run query** to apply the filter and display the telemetry pipeline output. **Example of OTEL Event Payload (GCP)** Exported OpenTelemetry events use structured JSON payloads for straightforward SIEM ingestion. Below is an example of an enforced policy violation (a blocked execution attempt) found within Google Cloud Logging: ```json { "timestamp": "2026-04-29T14:22:15.088Z", "severity": "ERROR", "message": "process '/usr/bin/bash' (12134) tried to execute '/usr/bin/date' [Action: Blocked]", "attributes": { "bluerock.action": "Blocked", "bluerock.policy_remediate": true, "process.executable.path": "/usr/bin/date", "process.parent.pid": 12134, "cloud.provider": "gcp", "cloud.account.id": "qa-staging-488516", "cloud.availability_zone": "us-central1-a", "host.name": "bluerockprem01-node" } } ``` #### **Viewing Events in Amazon Web Services (AWS)** During AWS EC2 deployments, the BlueRock OTEL collector is configured to use the `awscloudwatchlogs` exporter. Successful telemetry routing requires assigning an appropriate IAM Instance Profile to the deployment node to authorize CloudWatch ingestion. * **Destination:** Amazon CloudWatch Logs * **Enrichment:** Events are automatically structured and tagged by the OpenTelemetry pipeline before ingestion. **Querying the Logs:** 1. Access the AWS Management Console. 2. Navigate to **CloudWatch** > **Logs** > **Log Management**. 3. Locate and select the log group created by the deployment (for example: `bluerock-ec2-TelemetryLogGroup`). 4. Select the active log stream to view the live telemetry.\ ![](/files/OVz1u7G1CZ1b4myrUVo2) 5. Use the Filter events search bar to query for specific event types (e.g., type `"process_guard_violation"` to filter for blocked execution attempts). **Example OTEL Event Payload (AWS):**\ Exported OpenTelemetry events use structured JSON payloads. Below is an example of a blocked execution attempt as it appears in CloudWatch: ```json { "body": { "process_guard_violation": "", "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "'/usr/bin/bash' attempting to execute '/usr/bin/curl'" } } } ``` *** #### **Viewing Events Locally via Debug Exporter** By default, the OTEL Collector routes telemetry data to external platforms and does not print event payloads to the local console. Viewing events directly within the `otel-collector` container logs requires enabling the debug exporter. The debug exporter is a built-in OTEL component designed specifically to print telemetry data directly to the local standard output. Enabling the debug exporter verifies data ingestion and allows inspection of raw JSON payloads before network transmission. 1. **Modify the OTEL Configuration**\ Edit the configuration file located at `/opt/bluerock/otel/otel-config.yaml` to include the `debug` exporter.\ \ Add the `debug` exporter under the `exporters` section: 
exporters:
     awscloudwatchlogs:
       log_group_name: bluerock-ec2-TelemetryLogGroup
     debug:
       verbosity: detailed
\ Add the `debug` exporter to the logs pipeline under the `service` section: 
service:
     pipelines:
       logs:
         receivers: [otlp]
         processors: [resourcedetection, memory_limiter, batch]
         exporters: [awscloudwatchlogs, debug]
2. **Apply the Configuration**\ Restart the OpenTelemetry Collector container to apply the new pipeline configuration: 
$ sudo docker restart otel-collector
3. **View the Local Events** \ Trigger a sandboxed application event. The structured JSON payload will now print directly to the container's standard output. Use standard Docker logging commands to view the events: ```shellscript $ sudo docker logs -f otel-collector ``` Expected output: ```shellscript 2026/04/29 10:10:12 ADOT Collector version: v0.44.0 2026/04/29 10:10:12 found no extra config, skip it, err: open /opt/aws/aws-otel-collector/etc/extracfg.txt: no such file or directory 2026/04/29 10:10:12 attn: users of the `datadog`, `logzio`, `sapm`, `signalfx` exporter components. please refer to https://github.com/aws-observability/aws-otel-collector/issues/2734 in regards to an upcoming ADOT Collector breaking change 2026-04-29T10:10:12.950Z info service@v0.130.0/service.go:197 Setting up own telemetry... {"resource": {"service.instance.id": "2fc05024-935f-4a0d-9949-7de07f8d1422", "service.name": "aws-otel-collector", "service.version": "v0.44.0"}} 2026-04-29T10:10:12.951Z info builders/builders.go:26 Unmaintained component. Actively looking for contributors. Component will become deprecated after 3 months of remaining unmaintained. {"resource": {"service.instance.id": "2fc05024-935f-4a0d-9949-7de07f8d1422", "service.name": "aws-otel-collector", "service.version": "v0.44.0"}, "otelcol.component.id": "awscloudwatchlogs", "otelcol.component.kind": "exporter", "otelcol.signal": "logs"} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bluerock.io/bluerock-sandbox/bluerock-sandbox-observability.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.