github.com/m-lab/locate@v0.17.6/cmd/monitoring-token/README.md (about)

     1  # Running Command with Monitoring Tokens
     2  
     3  The locate service issues access tokens based on the client use-case.
     4  
     5  Clients using the `/v2/nearest` path receive access tokens for a specific
     6  service. Clients using the `/v2/platform/monitoring` path receive access tokens
     7  specifically for monitoring.
     8  
     9  These special purpose, monitoring access tokens allow the target server to
    10  identify monitoring requests and optionally handle them differently. For
    11  example, the target server could allow the request when another client would
    12  be rejected, or monitoring metrics could be updated differently.
    13  
    14  Because target servers treat monitoring access tokens differently than query
    15  access tokens, additional authorization is required before issuing monitoring
    16  access tokens. This authorization is provided using access tokens!
    17  
    18  The locate service uses a private signing key that issues access tokens. A
    19  privileged, end to end monitoring client will also have the ability to create
    20  access tokens to request monitoring access tokens from the locate service.
    21  
    22  Basic sequence diagram for a /v2/platform/monitoring request:
    23  
    24  ```txt
    25  Get access token: monitoring-token <------> locate/v2/platform/monitoring
    26  Use access token: e2e-client       -------> service
    27  ```
    28  
    29  For our end to end monitoring, we will use the `monitoring-token` command to
    30  get an access token from the locate service, pass a service URL to a command
    31  through an environment variable. For example:
    32  
    33  ```sh
    34  export LOCATE_URL=https://locate-dot-mlab-sandbox.appspot.com/v2/platform/monitoring/
    35  export MONITORING_SIGNER_KEY=/path/to/key.json
    36  
    37  monitoring-token \
    38      -machine=${MACHINE} \
    39      -service=ndt/ndt5 -- \
    40      ndt5-client -throttle=131072 -protocol=ndt5+wss
    41  ```
    42  
    43  ## Debug
    44  
    45  By default, `monitoring-token` does not report any extra output and the
    46  subcommand output is discarded. To report diagnostic information from
    47  `monitoring-token` and print the subcommand's stdout and stderr, use the
    48  `-logx.debug=true` flag.
    49  
    50  ```sh
    51  monitoring-token -logx.debug=true \
    52      ...
    53  ```