github.com/observiq/bindplane-agent@v1.51.0/docs/getting-started.md (about)

     1  # Getting Started
     2  
     3  OpenTelemetry is at the core of standardizing telemetry solutions. At observIQ, we’re focused on building the very best in open source telemetry software. Our relationship with OpenTelemetry began in 2021, with observIQ, contributing our logging agent, Stanza, to the OpenTelemetry community. Now, we are shifting our focus to simplifying OpenTelemetry solutions to its large base of users. On that note, we launched a collector that combines the best of both worlds, with OpenTelemetry at its core, combined with observIQ’s functionalities to simplify its usage.
     4  
     5  In this post, we are taking you through the installation of the BindPlane Agent and the steps to configure the agent to gather host metrics, eventually forwarding those metrics to the Google Cloud Operations.
     6  
     7  ## Installing the agent
     8  
     9  The simplest way to get started is with one of the single-line installation commands shown below. For more advanced options, you'll find a variety of installation options for Linux, Windows, and macOS on GitHub.
    10  
    11  Use the following single-line installation script to install the BindPlane Agent.
    12  Please note that the agent must be installed on the system which you wish to collect host metrics from.
    13  
    14  #### Windows:
    15  
    16  ```batch
    17  msiexec /i "https://github.com/observIQ/bindplane-agent/releases/latest/download/observiq-otel-collector.msi" /quiet
    18  ```
    19  
    20  #### Linux:
    21  
    22  ```shell
    23  sudo sh -c "$(curl -fsSlL https://github.com/observiq/bindplane-agent/releases/latest/download/install_unix.sh)" install_unix.sh
    24  ```
    25  
    26  For more details on installation, see our [Linux](/docs/installation-linux.md), [Windows](/docs/installation-windows.md), and [Mac](/docs/installation-mac.md) installation guides.
    27  
    28  ## Setting up pre-requisites and authentication credentials
    29  
    30  In the following example, we are using Google Cloud Operations as the destination. However, OpenTelemetry offers exporters for many destinations. Check out the list of exporters [here](/docs/exporters.md). 
    31  
    32  ### Setting up Google Cloud exporter prerequisites:
    33  
    34  If running outside of Google Cloud (On prem, AWS, etc) or without the Cloud Monitoring scope, the Google Exporter requires a service account.
    35  Create a service account with the following roles:
    36  
    37  Metrics: `roles/monitoring.metricWriter`
    38  
    39  Logs: `roles/logging.logWriter`
    40  
    41  Create a service account JSON key and place it on the system that is running the collector.
    42  
    43  ### Linux
    44  
    45  In this example, the key is placed at `/opt/observiq-otel-collector/sa.json` and its permissions are restricted to the user running the collector process.
    46  
    47  ```shell
    48  sudo cp sa.json /opt/observiq-otel-collector/sa.json
    49  sudo chown observiq-otel-collector: /opt/observiq-otel-collector/sa.json
    50  sudo chmod 0400 /opt/observiq-otel-collector/sa.json
    51  ```
    52   
    53  Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable by creating a systemd override. A systemd override allows users to modify the systemd service configuration without modifying the service directly. This allows package upgrades to happen seamlessly. You can learn more about systemd units and overrides here.
    54  
    55  Run the following command
    56  
    57  ```shell
    58  sudo systemctl edit observiq-otel-collector
    59  ```
    60  
    61  If this is the first time an override is being created, paste the following contents into the file:
    62  
    63  ```
    64  [Service]
    65  Environment=GOOGLE_APPLICATION_CREDENTIALS=/opt/observiq-otel-collector/sa.json
    66  ```
    67   
    68  If an override is already in place, simply insert the Environment parameter into the existing Service section.
    69  
    70  Restart the agent
    71  
    72  ```shell
    73  sudo systemctl restart observiq-otel-collector
    74  ```
    75   
    76  ### Windows
    77  
    78  In this example, the key is placed at `C:/observiq/collector/sa.json`.
    79  Set the `GOOGLE_APPLICATION_CREDENTIALS` with the command prompt setx command.
    80  
    81  Run the following command
    82  
    83  ```batch
    84  setx GOOGLE_APPLICATION_CREDENTIALS "C:/observiq/collector/sa.json" /m
    85  ```
    86   
    87  Restart the service using the services application.
    88  
    89  ## Configuring the agent
    90  
    91  In this sample configuration, the steps to use the host metrics receiver to fetch metrics from the host system and export them to Google Cloud Operations are detailed. This is how it works:
    92  
    93  The agent scrapes metrics and logs from the host and exports them to a destination assigned in the configuration file. 
    94  To export the metrics to Google Cloud Operations, use the configurations outlined in the googlecloudexporter as in the example `config.yaml` below.
    95  
    96  After the installation, the config file for the agent can be found at:
    97  
    98  Windows: `C:\Program Files\observIQ OpenTelemetry Collector\config.yaml`
    99  
   100  Linux: `/opt/observiq-otel-collector/config.yaml`
   101  
   102  Edit the configuration file and use the following configuration.
   103  
   104  ```yaml
   105  # Receivers collect metrics from a source. The host metrics receiver will
   106  # get CPU load metrics about the machine the agent is running on
   107  # every minute.
   108  receivers:
   109    hostmetrics:
   110      collection_interval: 60s
   111      scrapers:
   112        cpu:
   113        disk:
   114        load:
   115        filesystem:
   116        memory:
   117        network:
   118        paging:
   119        processes:
   120  
   121  # Exporters send the data to a destination, in this case GCP.
   122  exporters:
   123    googlecloud:
   124  
   125  # Service specifies how to construct the data pipelines using
   126  # the configurations above.
   127  service:
   128    pipelines:
   129      metrics:
   130        receivers: [hostmetrics]
   131        exporters: [googlecloud]
   132  ```
   133  
   134  Restart the agent
   135  
   136  ```shell
   137  systemctl restart observiq-otel-collector
   138  ```
   139  
   140  ## Viewing the metrics in Google Cloud Operations
   141  
   142  You should now be able to view the host metrics in your Metrics explorer. Nice work! This is how simple it is to collect host metrics with the BindPlane Agent.
   143  
   144  ### Metrics collected
   145  
   146  | Metric | Description | Metric Namespace |
   147  | --- | --- | --- |
   148  | Processes Created | Total number of created processes. | custom.googleapis.com/opencensus/system.processes.created |
   149  | Process Count | Total number of processes in each state. | custom.googleapis.com/opencensus/system.processes.count |
   150  | Process CPU time | Total CPU seconds broken down by different states. | custom.googleapis.com/opencensus/process.cpu.time |
   151  | Process Disk IO | Disk bytes transferred. | custom.googleapis.com/opencensus/process.disk.io |
   152  | File System Inodes Used | FileSystem inodes used. | custom.googleapis.com/opencensus/system.filesystem.inodes.usage |
   153  | File System Utilization | Filesystem bytes used. | custom.googleapis.com/opencensus/system.filesystem.usage |
   154  | Process Physical Memory Utilization | The amount of physical memory in use. | custom.googleapis.com/opencensus/process.memory.physical_usage |
   155  | Process Virtual Memory Utilization | Virtual memory size. | custom.googleapis.com/opencensus/process.memory.virtual_usage |
   156  | Networking Errors | The number of errors encountered. | custom.googleapis.com/opencensus/system.network.errors |
   157  | Networking Connections | The number of connections. | custom.googleapis.com/opencensus/system.network.connections |
   158  
   159  ## What Next?
   160  
   161  Check out our list of supported [receivers](), [processors](), [exporters](), and [extensions]() for more information about making a config. To see more monitoring examples, be sure to follow the [Observability Blog](https://observiq.com/blog/).
   162  
   163  observIQ’s distribution is a game-changer for companies looking to implement the OpenTelemetry standards. The single line installer, seamlessly integrated receivers, exporter, and processor pool make working with this agent simple. For questions, requests, and suggestions, reach out to our support team at support@observIQ.com.