Usage

This section guides you through the complete process of deploying and managing Observo AI Edge Collectors across Windows, Linux, and macOS environments. From initial setup and agent configuration to ongoing maintenance and troubleshooting, these step-by-step instructions help security and DevOps teams efficiently manage telemetry data collection at scale. Leveraging the centralized, OTel-based Fleet Management system, you can streamline onboarding, optimize data flow, and ensure consistent observability across hybrid infrastructures.

The overall Fleet Management process consists of a seven (7) step process:

1. Add Fleet (if not exit)

2. Add OpenTelemetry Source (or use existing one)

3. Add OTEL configurations

   • Add Configuration Metadata

   • Add Otel Receiver/Full Raw OTEL Configurations

   • Add the Destination (Open Telemetry Source)

   • Save (Update)

4. Install Agent (based on OS)

   • Requires Site, Platform, Architecture, Fleet, OTEL Configurations, Configuration Version information

   • Generate Agent install script

   • Install Agent on Windows, Linux or macOs node

   • Allow access to any log, metric or traces based on OS access commands

5. Update Configuration (if required before deployment)

6. Deploy the Configuration

7. Build a Pipeline (based on Open Telemetry Source added in Step 2)

Perform these steps on each OS platform, or automate the process using orchestration tools.

Additional guidance is provided for Post-Installation: Verification, Troubleshooting Common Issues, Maintenance and Updates, Best Practices, and Agent Cleanup.

1. Add Fleet (if not exist)

1. Navigate to Fleet Management tab

2. Click on the Add Fleet button

3. Add Name (required)

4. Add Description (Optional but best practice)

2. Add Open-Telemetry Source (or use existing one)

1. Choose OpenTelemetry as the source type.

2. For Name, enter any unique identifier (it must be unique).

3. Description is optional — you can provide any helpful context.

4. Set the gRPC Address to 0.0.0.0:<unused-port> — make sure to use a port that is not currently in use.

5. Set the HTTP Address to 0.0.0.0:<port>. The port number should match the one used for the gRPC address.

3. Add OTel Configurations

• Go to Fleet Manager and select the Configurations tab

• Click the Add Configuration button.

• From the dropdown, choose a Site where this configuration will be applied.

Next, select a Configuration Type — two types are available:

1. Full Raw OTel Config: This allows users to submit a complete OpenTelemetry pipeline including receivers, processors, and exporters.

   Here the configuration is completely defined by the user. Here Observo will act only as configuration management and deployment. Users are free to choose their own destinations as they want.

   See OTel Receiver Examples (Windows, Linux, macOS).

2. Receiver Config Only: This option allows users to define only the receiver section. Users can add multiple receivers by clicking the Add button. The remaining pipeline (processors/exporters) is handled by the system.

   This flow will restrict users to send data Observo sources only.

Finally, choose a Destination from the dropdown to specify where the collected data should be sent.

See OTel Full Raw Configuration Examples (Windows, Linux, macOS).

4. Install Agent (Based on OS)

The agent installation process generates platform-specific scripts based on your configuration requirements and deploys agents to target systems. After installation, appropriate OS-level permissions must be configured.

Note: Before proceeding, confirm that ports 4320 (OTel Logs), 9090 (OTel Metrics), and any OpenTelemetry source ports configured in Step 2 are open and reachable on the target Windows, Linux, or macOS host.

Generate Agent Install Script

• Navigate to Fleet Management->Agents

• Select the Install Agent button (upper right)

• Choose a Site from the dropdown.

• Select the Platform such as Windows, Linux or macOs

• Select the Architecture such as ARM64 or AMD64

• Choose a Fleet from the dropdown such as Default.

• Select the Configuration (LinuxVarLogs or WinEventLogs)

• Choose the desired Configuration Version.

• Click Next — this will generate the agent install script such as a PowerShell installation script.

Copy the script and run this script on your platform such as the Windows machine to install and register the agent. You can use an orchestration solution to deploy the agent to multiple servers.

Install Agent

Install the agent based on the supported OS types:

• Windows

• Linux

• macOS

Windows Install

For an installation of the agent on a Windows system, the Fleet Management UI generates a PowerShell command tailored for one-off deployments. Below is an illustrative example of what such a command might look like when copied from the Fleet Management UI:

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/Observo-Inc/observo-shared/main/edge/install.ps1" -OutFile "$env:TEMP\install.ps1"; powershell.exe -ExecutionPolicy Bypass -File "$env:TEMP\install.ps1" -EnvVar "install_id=[AUTH TOKEN] download_url=[Download URL]"

Ensure that you Run as Administrator to allow for the installation to complete

Check if Windows Agent Installed Correctly To verify a successful installation, follow these proceeding steps to check if the Windows Agent is installed correctly.

Check Running Windows Processes

Open PowerShell and run: Get-Process edge, otelcontribcol_windows_amd64 -ErrorAction SilentlyContinue You should see two processes edge and otelcontribcol_windows_amd64

Verify Windows Log Files

List files in the log directory:

Get-ChildItem -Path 'C:\Program Files\Observo\logs'

You should see both:

edge-collector.log
observoedge_stdout.log

Check Effective Windows YAML Configuration Run the following command to view the current applied config:

Get-Content 'C:\Program Files\Observo\effective.yaml'

Linux Install

This section is reserved for Linux. Updates will follow based on available Linux functionality.

Step 1: Detect System Architecture Determine OS and architecture for compatibility to ensure that you generated the correct agent install script.

Here are the Linux environments:

• x86_64 (ARCH=amd64): 64-bit x86 architecture for modern Linux desktops, servers, and cloud instances, ideal for high-performance agent deployments.

• arm64|aarch64 (ARCH=arm64): 64-bit ARM for energy-efficient devices like Raspberry Pi 4/5 and cloud servers, suited for edge and IoT agent setups.

• armv7l (ARCH=armv7): 32-bit ARM for older embedded devices and IoT, used for lightweight agent installations on minimal Linux systems.

• i386|i686 (ARCH=386): 32-bit x86 for legacy PCs and minimal Linux, rarely used for basic agent deployments on outdated hardware.

uname -m
x86_64

Step 2: Linux Install

For an installation of the agent on a Linux system, the Fleet Management UI generates a bash command tailored for one-off deployments. Copy the bash command and run it on the command line as sudo. Below is an illustrative example of what such a command might look like when copied from the Fleet Management UI:

sudo bash -c "$(curl -fsSlL 'https://raw.githubusercontent.com/Observo-Inc/observo-shared/main/edge//install.sh')" install.sh -e 'install_id=[AUTH TOKEN] download_url=h[Download URL]'

Step 5: Verify Linux Agent Install Status: Check to ensure the observo-agent is running.

sudo systemctl status observo-agent
journalctl -u observo-agent -f

Check running processes:

ps aux | grep -E 'edge|otelcontrib'

(Should show edge and otelcontribcol_linux_*.)

Check logs:

sudo ls -la /var/log/observo/
sudo tail -f /var/log/observo/observo-agent.log

View effective config (if applicable, based on Windows doc analogy):

cat /opt/observo/edge-config.json

macOS Install

This section is reserved for macOS. Updates will follow based on available macOS functionality.

Configure OS Access Permissions

After installation, configure appropriate system-level access for telemetry collection:

• Windows: Configure Event Log access, WMI permissions, and application log access. The running processes will be edge and otelcontribcol_windows_amd64. Use the appropriate wevtutil, icacls and net localgroup commands.

• Linux: Set up log file permissions, user groups, and sudoers configuration. Such as sudo usermod \-aG adm observo

• macOS: Enable Full Disk Access and configure system log permissions. Use the appropriate dseditgroup, dscl and chmod commands.

5. Update Configuration (if required before deployment)

Configuration settings established during the Create Configuration process can be modified as needed before deployment.

An OpenTelemetry receiver ingests telemetry data (metrics, logs, traces) in specific formats from agents or services and forwards it through a processing pipeline. A full raw configuration typically involves setting up every pipeline component manually—receivers, processors, exporters—offering complete control over data flow, transformation, and export.

Update Full Raw OTel Config

1. Go to Fleet Manager → Configurations

2. Find the Raw OTel configuration you want to update.

3. Click Edit - This opens the YAML editor.

4. Make Changes

5. Update receivers, processors, exporters, etc. as needed.

6. Click Save

A new configuration version will be created.

Update Receiver Config

1. Go to Fleet Manager → Configurations

2. Click Edit - This opens the Receiver graph.

3. Update an Existing Receiver - Click on each receiver block to edit its fields

4. Add a New Receiver

   • Click on the three-dot menu (⋮) beside any receiver.

   • Select “Add Another Receiver” from the dropdown.

   • Add the config.

1. Click Save

• A new version of the config will be created.

6. Deploy the Configuration

To deploy the updated configuration, you can either (1) deploy via Agent/Fleet or (2) use the Agent table option.

Deploy Agent/Fleet

• Click the Deploy Agent/Fleet(s) button on the right side.

• In the pop-up, switch to the Agents tab.

• Select the agent(s) you want to deploy the config to.

• Click Deploy.

Update Agent Deployment (if newer version) You can also deploy the updated configuration directly from the Agents table:

1. Go to the Agents tab in Fleet Manager.

2. Find the agent showing a warning icon (⚠️) — this indicates it’s running an older version of the configuration.

3. Hover over the warning and click Deploy latest version.

4. A pop-up will appear.

   • Select just that agent or multiple agents if needed. Click Deploy to push the latest config version.

7. Build a Pipeline (based on Open Telemetry Source)

Use the existing Open Telemetry Source created in Step 2 to add an OTEL receiver-based pipeline. An OTEL receiver is a pre-configured component that ingests telemetry data from specific sources using standardized OpenTelemetry protocols and formats. It provides a simplified, template-based approach for common data collection scenarios with predefined settings and limited customization options.

Use the existing Open Telemetry Source created in Step 2 to add an OTel Full Raw Configuration-based pipeline. OTel Full Raw Configuration provides complete, unprocessed access to the entire OpenTelemetry configuration structure in its native YAML format. This allows for advanced custom receiver setups, complex pipeline configurations, and full control over all OpenTelemetry parameters beyond what standard receiver templates offer.

Note: You can create multiple OTel-based pipelines using the same data sources, allowing for different data optimization, normalization, and enrichment and routing configurations.

Post-Installation

Additional guidance is provided for Post-Installation:

• Verification Steps

• Troubleshooting Common Issues

• Maintenance and Updates

• Best Practices

• Agent Cleanup

Verification Steps

1. Service Status Check:

   • Windows: Get-Service ObservoAgent

   • Linux: systemctl status observo-agent

   • macOS: launchctl list | grep observo

2. Configuration Validation:

   • Check agent configuration file location

   • Verify endpoint connectivity

   • Confirm authentication token validity

3. Data Flow Testing:

   • Generate test telemetry data

   • Verify data appears in Observo AI dashboard

   • Check for any error messages or warnings

4. Performance Monitoring:

   • Monitor agent resource usage

   • Check system impact metrics

   • Verify data processing rates

Troubleshooting Common Issues

Agent Installation Failures:

• Permission Issues: Ensure installation runs with administrative privileges

• Network Connectivity: Verify firewall rules and network access

• Configuration Errors: Validate configuration syntax and parameters

Data Collection Issues:

• Log Access: Verify appropriate file and directory permissions

• Metric Collection: Confirm WMI/system access permissions

• Trace Reception: Check port availability and firewall configurations

Performance Issues:

• High CPU Usage: Review configuration complexity and data volume

• Memory Consumption: Adjust batching and buffer configurations

• Network Bandwidth: Implement compression and optimize transmission intervals

Maintenance and Updates

Regular Maintenance Tasks:

1. Agent Updates: Deploy new agent versions through fleet management

2. Configuration Updates: Push configuration changes centrally

3. Performance Monitoring: Review agent health and performance metrics

4. Security Updates: Maintain current authentication tokens and certificates

Scaling Considerations:

• Horizontal Scaling: Deploy agents across multiple systems

• Load Balancing: Distribute data collection load appropriately

• Resource Optimization: Tune configurations for optimal performance

• Centralized Management: Leverage fleet management for operational efficiency

Best Practices

Security:

• Use least-privilege access principles

• Regularly rotate authentication tokens

• Implement network segmentation where appropriate

• Monitor agent access logs for anomalies

Operations:

• Implement configuration version control

• Establish deployment rollback procedures

• Monitor agent health and performance metrics

• Maintain documentation and change logs

Performance:

• Optimize data collection intervals

• Implement appropriate data filtering

• Use compression for network transmission

• Balance real-time needs with resource usage

This guide provides the foundation for successful Observo AI Edge Collector deployment and management across diverse infrastructure environments.

Clean the Agent

Clean up the Windows, Linux, or macOS agent if required.

Clean Windows Agent

To completely remove the Observo Edge agent from a Windows machine run the following commands:

Unregister-ScheduledTask -TaskName "ObservoEdge" -Confirm:$false;
Stop-Process -Name edge -Force;
Stop-Process -Name otelcontribcol_windows_amd64 -Force;
Remove-Item "C:\Program Files\Observo" -Recurse -Force;
Remove-Item "C:\Windows\TEMP\install.ps1";

Clean Linux Agent

To fully remove the Observo AI agent from a Linux system, follow these steps in order. This process assumes you have root or sudo access. Run commands as root (or prefix with sudo). Be cautious, as these actions are irreversible and may affect system stability if other processes depend on the user, group, or files. It's recommended to back up important data first.

Stop and Disable the Systemd Service

Stop the running service and disable it from starting on boot:

sudo systemctl stop observo-agent
sudo systemctl disable observo-agent

This prevents the agent from running during cleanup.

Remove the Systemd Service File Delete the service unit file (typically located in /etc/systemd/system/ or /lib/systemd/system/):

sudo rm /etc/systemd/system/observo-agent.service

If it's in /lib/systemd/system/, adjust the path accordingly. Then reload systemd:

sudo systemctl daemon-reload

Remove Log Files Delete the log directory and its contents:

sudo rm -rf /var/log/observo/

Verify with ls /var/log/ to ensure it's gone.

Kill Any Remaining Processes

Check for and terminate any lingering observo-agent processes: pkill -f observo-agent Or, if needed, use ps aux | grep observo to identify PIDs and kill <PID>.

Remove the Installation Directory

Delete the main agent files:

sudo rm -rf /opt/observo

This removes the binaries and configuration files.

Remove the User and Group

First, ensure no processes are running as the observo user (step 4 should handle this). Then delete the user and group:

sudo userdel --remove observo
sudo groupdel observo

• The --remove option deletes the user's home directory (if any) and mail spool.

• If the user has active sessions, use userdel -f --remove observo to force removal, but this is risky and may leave files behind.

Verification

• Check services: systemctl status observo-agent (should show "inactive" or "not found").

• Check users/groups: id observo and getent group observo (should return "no such user/group").

• Check directories: ls /opt/observo and ls /var/log/observo (should not exist).

• Reboot the system and confirm the agent doesn't restart.

If the agent was installed via a package manager such as RPM or DEB, consider using rpm -e observo-agent or apt remove observo-agent first for a cleaner uninstall. For custom scripted installs, contact the Observo AI sales team if issues arise.

Clean macOS Agent

This section is reserved for macOS. Updates will follow based on available macOS functionality.

Resources

For additional guidance and detailed information, refer to the following resources:

Platform-Specific Resources

• Windows Event Logging: Microsoft documentation on configuring and auditing Windows event logs for telemetry collection.

• Linux Syslog and Logging: Guide to Linux logging mechanisms, including syslog and journald, for configuring Edge Collectors.

• Linux Security Logs: Complete Guide for DevOps and SysAdmins: Resource for generating and managing Linux security logs.

• macOS Unified Logging: Documentation on macOS logging for telemetry collection