github.com/netdata/go.d.plugin@v0.58.1/modules/dnsmasq/integrations/dnsmasq.md (about)

     1  <!--startmeta
     2  custom_edit_url: "https://github.com/netdata/go.d.plugin/edit/master/modules/dnsmasq/README.md"
     3  meta_yaml: "https://github.com/netdata/go.d.plugin/edit/master/modules/dnsmasq/metadata.yaml"
     4  sidebar_label: "Dnsmasq"
     5  learn_status: "Published"
     6  learn_rel_path: "Data Collection/DNS and DHCP Servers"
     7  most_popular: False
     8  message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
     9  endmeta-->
    10  
    11  # Dnsmasq
    12  
    13  
    14  <img src="https://netdata.cloud/img/dnsmasq.svg" width="150"/>
    15  
    16  
    17  Plugin: go.d.plugin
    18  Module: dnsmasq
    19  
    20  <img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />
    21  
    22  ## Overview
    23  
    24  This collector monitors Dnsmasq servers.
    25  
    26  
    27  
    28  
    29  This collector is supported on all platforms.
    30  
    31  This collector supports collecting metrics from multiple instances of this integration, including remote instances.
    32  
    33  
    34  ### Default Behavior
    35  
    36  #### Auto-Detection
    37  
    38  This integration doesn't support auto-detection.
    39  
    40  #### Limits
    41  
    42  The default configuration for this integration does not impose any limits on data collection.
    43  
    44  #### Performance Impact
    45  
    46  The default configuration for this integration is not expected to impose a significant performance impact on the system.
    47  
    48  
    49  ## Metrics
    50  
    51  Metrics grouped by *scope*.
    52  
    53  The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.
    54  
    55  
    56  
    57  ### Per Dnsmasq instance
    58  
    59  The metrics apply to the entire monitored application.
    60  
    61  This scope has no labels.
    62  
    63  Metrics:
    64  
    65  | Metric | Dimensions | Unit |
    66  |:------|:----------|:----|
    67  | dnsmasq.servers_queries | success, failed | queries/s |
    68  | dnsmasq.cache_performance | hist, misses | events/s |
    69  | dnsmasq.cache_operations | insertions, evictions | operations/s |
    70  | dnsmasq.cache_size | size | entries |
    71  
    72  
    73  
    74  ## Alerts
    75  
    76  There are no alerts configured by default for this integration.
    77  
    78  
    79  ## Setup
    80  
    81  ### Prerequisites
    82  
    83  No action required.
    84  
    85  ### Configuration
    86  
    87  #### File
    88  
    89  The configuration file name for this integration is `go.d/dnsmasq.conf`.
    90  
    91  
    92  You can edit the configuration file using the `edit-config` script from the
    93  Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#the-netdata-config-directory).
    94  
    95  ```bash
    96  cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
    97  sudo ./edit-config go.d/dnsmasq.conf
    98  ```
    99  #### Options
   100  
   101  The following options can be defined globally: update_every, autodetection_retry.
   102  
   103  
   104  <details><summary>Config options</summary>
   105  
   106  | Name | Description | Default | Required |
   107  |:----|:-----------|:-------|:--------:|
   108  | update_every | Data collection frequency. | 1 | no |
   109  | autodetection_retry | Recheck interval in seconds. Zero means no recheck will be scheduled. | 0 | no |
   110  | address | Server address in `ip:port` format. | 127.0.0.1:53 | yes |
   111  | protocol | DNS query transport protocol. Supported protocols: udp, tcp, tcp-tls. | udp | no |
   112  | timeout | DNS query timeout (dial, write and read) in seconds. | 1 | no |
   113  
   114  </details>
   115  
   116  #### Examples
   117  
   118  ##### Basic
   119  
   120  An example configuration.
   121  
   122  <details><summary>Config</summary>
   123  
   124  ```yaml
   125  jobs:
   126    - name: local
   127      address: 127.0.0.1:53
   128  
   129  ```
   130  </details>
   131  
   132  ##### Using TCP protocol
   133  
   134  Local server with specific DNS query transport protocol.
   135  
   136  <details><summary>Config</summary>
   137  
   138  ```yaml
   139  jobs:
   140    - name: local
   141      address: 127.0.0.1:53
   142      protocol: tcp
   143  
   144  ```
   145  </details>
   146  
   147  ##### Multi-instance
   148  
   149  > **Note**: When you define multiple jobs, their names must be unique.
   150  
   151  Collecting metrics from local and remote instances.
   152  
   153  
   154  <details><summary>Config</summary>
   155  
   156  ```yaml
   157  jobs:
   158    - name: local
   159      address: 127.0.0.1:53
   160  
   161    - name: remote
   162      address: 203.0.113.0:53
   163  
   164  ```
   165  </details>
   166  
   167  
   168  
   169  ## Troubleshooting
   170  
   171  ### Debug Mode
   172  
   173  To troubleshoot issues with the `dnsmasq` collector, run the `go.d.plugin` with the debug option enabled. The output
   174  should give you clues as to why the collector isn't working.
   175  
   176  - Navigate to the `plugins.d` directory, usually at `/usr/libexec/netdata/plugins.d/`. If that's not the case on
   177    your system, open `netdata.conf` and look for the `plugins` setting under `[directories]`.
   178  
   179    ```bash
   180    cd /usr/libexec/netdata/plugins.d/
   181    ```
   182  
   183  - Switch to the `netdata` user.
   184  
   185    ```bash
   186    sudo -u netdata -s
   187    ```
   188  
   189  - Run the `go.d.plugin` to debug the collector:
   190  
   191    ```bash
   192    ./go.d.plugin -d -m dnsmasq
   193    ```
   194  
   195