github.com/netdata/go.d.plugin@v0.58.1/pkg/web/README.md (about)

     1  <!--
     2  title: "web"
     3  custom_edit_url: "https://github.com/netdata/go.d.plugin/edit/master/pkg/web/README.md"
     4  sidebar_label: "web"
     5  learn_status: "Published"
     6  learn_rel_path: "Developers/External plugins/go.d.plugin/Helper Packages"
     7  -->
     8  
     9  # web
    10  
    11  This package contains HTTP related configurations (`Request`, `Client` and `HTTP` structs) and functions to
    12  create `http.Request` and `http.Client` from them.
    13  
    14  `HTTP` embeds both `Request` and `Client`.
    15  
    16  Every module that collects metrics doing HTTP requests should use `HTTP`. It allows to have same set of user
    17  configurable options across all modules.
    18  
    19  ## Configuration options
    20  
    21  HTTP request options:
    22  
    23  - `url`: the URL to access.
    24  - `username`: the username for basic HTTP authentication.
    25  - `password`: the password for basic HTTP authentication.
    26  - `proxy_username`: the username for basic HTTP authentication of a user agent to a proxy server.
    27  - `proxy_password`: the password for basic HTTP authentication of a user agent to a proxy server.
    28  - `body`: the HTTP request body to be sent by the client.
    29  - `method`: the HTTP method (GET, POST, PUT, etc.).
    30  - `headers`: the HTTP request header fields to be sent by the client.
    31  
    32  HTTP client options:
    33  
    34  - `timeout`: the HTTP request time limit.
    35  - `not_follow_redirects`: the policy for handling redirects.
    36  - `proxy_url`: the URL of the proxy to use.
    37  - `tls_skip_verify`: controls whether a client verifies the server's certificate chain and host name.
    38  - `tls_ca`: certificate authority to use when verifying server certificates.
    39  - `tls_cert`: tls certificate to use.
    40  - `tls_key`: tls key to use.
    41  
    42  ## Usage
    43  
    44  Just make `HTTP` part of your module configuration.
    45  
    46  ```go
    47  package example
    48  
    49  import "github.com/netdata/go.d.plugin/pkg/web"
    50  
    51  type Config struct {
    52  	web.HTTP `yaml:",inline"`
    53  }
    54  
    55  type Example struct {
    56  	Config `yaml:",inline"`
    57  }
    58  
    59  func (e *Example) Init() bool {
    60  	httpReq, err := web.NewHTTPRequest(e.Request)
    61  	if err != nil {
    62  		// ...
    63  		return false
    64  	}
    65  
    66  	httpClient, err := web.NewHTTPClient(e.Client)
    67  	if err != nil {
    68  		// ...
    69  		return false
    70  	}
    71  
    72  	// ...
    73  	return true
    74  }
    75  ```
    76  
    77  Having `HTTP` embedded your configuration inherits all [configuration options](#configuration-options):
    78  
    79  ```yaml
    80  jobs:
    81    - name: name
    82      url: url
    83      username: username
    84      password: password
    85      proxy_url: proxy_url
    86      proxy_username: proxy_username
    87      proxy_password: proxy_password
    88      timeout: 1
    89      method: GET
    90      body: '{"key": "value"}'
    91      headers:
    92        X-API-Key: key
    93      not_follow_redirects: no
    94      tls_skip_verify: no
    95      tls_ca: path/to/ca.pem
    96      tls_cert: path/to/cert.pem
    97      tls_key: path/to/key.pem
    98  ```