github.com/google/cloudprober@v0.11.3/docs/content/getting-started.md (about)

     1  ---
     2  menu:
     3      main:
     4          weight: -90
     5  title: Getting Started
     6  ---
     7  
     8  ## Installation
     9  
    10  * __From Source__  
    11  If you have Go 1.9 or higher installed and GOPATH environment variable properly set up, you
    12  can download and install `cloudprober` using the following commands:
    13  
    14    ```bash
    15    go get github.com/google/cloudprober
    16    GOBIN=$GOPATH/bin go install $GOPATH/src/github.com/google/cloudprober/cmd/cloudprober.go
    17    ```
    18  
    19  * __Pre-built Binaries__  
    20  You can download pre-built binaries for Linux, MacOS and Windows from the
    21  project's [releases page](http://github.com/google/cloudprober/releases).  
    22  (_See [this page](
    23  https://github.com/google/cloudprober/wiki/Download-unreleased-binaries) for
    24  how to download the unreleased binaries._)
    25  
    26  * __Docker Image__
    27  You can download and run the [latest](
    28  https://github.com/google/cloudprober/wiki/Docker-versions) docker image using
    29  the following command:
    30  
    31    ```bash
    32    docker run --net host cloudprober/cloudprober
    33    # Note: "--net host" provides better network performance and makes port
    34    # forwarding management easier, but is not required.
    35    ```
    36  
    37  ## Configuration
    38  
    39  Without any config, cloudprober will run only the "sysvars" module (no probes) and write metrics to stdout in cloudprober's line protocol format (to be documented). It will also start a [Prometheus](http://prometheus.io) exporter at: http://localhost:9313 (you can change the default port through the environment variable *CLOUDPROBER_PORT* and the default listening address through the environment variable *CLOUDPROBER_HOST*).
    40  
    41  Since sysvars variables are not very interesting themselves, lets add a simple
    42  config that probes Google's homepage:
    43  
    44  ```bash
    45  # Write config to a file in /tmp
    46  cat > /tmp/cloudprober.cfg <<EOF
    47  probe {
    48    name: "google_homepage"
    49    type: HTTP
    50    targets {
    51      host_names: "www.google.com"
    52    }
    53    interval_msec: 5000  # 5s
    54    timeout_msec: 1000   # 1s
    55  }
    56  EOF
    57  ```
    58  
    59  This config adds an HTTP probe that accesses the homepage of the target "www.google.com" every 5s with a timeout of 1s. Cloudprober configuration is specified in the text protobuf format, with config schema described by the proto file: [config.proto](https://github.com/google/cloudprober/blob/master/config/proto/config.proto).
    60  
    61  Assuming that you saved this file at `/tmp/cloudprober.cfg` (following the command above), you can have cloudprober use this config file using the following command line:
    62  
    63  ```bash
    64  ./cloudprober --config_file /tmp/cloudprober.cfg
    65  ```
    66  
    67  You can have the standard docker image use this config using the following
    68  command:
    69  
    70  ```bash
    71  docker run --net host -v /tmp/cloudprober.cfg:/etc/cloudprober.cfg \
    72      cloudprober/cloudprober
    73  ```
    74  
    75  Note: While running on GCE, cloudprober config can also be provided through a
    76  custom metadata attribute: __cloudprober\_config__.
    77  
    78  ## Verification
    79  
    80  One quick way to verify that cloudprober got the correct config is to access the URL `http://localhost:9313/config` (through cURL or in browser). It returns the config that cloudprober is using. You can also look at its current status at the URL (_replace localhost by the actual hostname if not running locally_): `http://localhost:9313/status`.
    81  
    82  You should be able to see the generated metrics at `http://localhost:9313/metrics` (prometheus format) and the stdout (cloudprober format):
    83  
    84  ```bash
    85  cloudprober 15.. 1500590520 labels=ptype=http,probe=google-http,dst=.. total=17 success=17 latency=180835
    86  cloudprober 15.. 1500590530 labels=ptype=sysvars,probe=sysvars hostname="manugarg-ws" uptime=100
    87  cloudprober 15.. 1500590530 labels=ptype=http,probe=google-http,dst=.. total=19 success=19 latency=211644
    88  ```
    89  
    90  This information is good for debugging monitoring issues, but to really make sense of this data, you'll need to feed this data to another monitoring system like _Prometheus_ or _StackDriver_ (see [Surfacers](/surfacers/overview) for more details). Lets set up a Prometheus and Grafana stack to make pretty graphs for us.
    91  
    92  ## Running Prometheus
    93  
    94  Download prometheus binary from its [release page](https://prometheus.io/download/). You can use a config like the following
    95  to scrape a cloudprober instance running on the same host.
    96  
    97  ```bash
    98  # Write config to a file in /tmp
    99  cat > /tmp/prometheus.yml <<EOF
   100  scrape_configs:
   101    - job_name: 'cloudprober'
   102      scrape_interval: 10s
   103      static_configs:
   104        - targets: ['localhost:9313']
   105  EOF
   106  
   107  # Start prometheus:
   108  ./prometheus --config.file=/tmp/prometheus.yml
   109  ```
   110  
   111  Prometheus provides a web interface at http://localhost:9090. You can explore probe metrics and
   112  build useful graphs through this interface. All probes in cloudprober export at least 3 counters:
   113  
   114  * _total_: Total number of probes.
   115  * _success_: Number of successful probes. Difference between _total_ and
   116  _success_ indicates failures.
   117  * _latency_: Total (cumulative) probe latency.
   118  
   119  Using these counters, probe failure ratio and average latency can be calculated
   120  as:
   121  
   122  ```bash
   123  failure_ratio = (rate(total) - rate(success)) / rate(total)
   124  avg_latency   = rate(latency) / rate(success)
   125  ```
   126  
   127  Assuming that prometheus is running at `localhost:9090`, graphs depicting
   128  failure ratio and latency over time can be accessed in prometheus at: [this url ]("http://localhost:9090/graph?g0.range_input=1h&g0.expr=(rate(total%5B1m%5D)+-+rate(success%5B1m%5D))+%2F+rate(total%5B1m%5D)&g0.tab=0&g1.range_input=1h&g1.expr=rate(latency%5B1m%5D)+%2F+rate(success%5B1m%5D)+%2F+1000&g1.tab=0").
   129  Even though prometheus provides a graphing interface, Grafana provides much
   130  richer interface and has excellent support for prometheus.
   131  
   132  ## Grafana
   133  
   134  [Grafana](https://grafana.com) is a popular tool for building monitoring dashboards. Grafana has native support for prometheus and thanks to the excellent support for prometheus in Cloudprober itself, it's a breeze to build Grafana dashboards from Cloudprober's probe results.
   135  
   136  To get started with Grafana, follow the Grafana-Prometheus
   137  [integration guide](https://prometheus.io/docs/visualization/grafana/).