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

     1  <!--startmeta
     2  custom_edit_url: "https://github.com/netdata/go.d.plugin/edit/master/modules/dnsquery/README.md"
     3  meta_yaml: "https://github.com/netdata/go.d.plugin/edit/master/modules/dnsquery/metadata.yaml"
     4  sidebar_label: "DNS query"
     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  # DNS query
    12  
    13  
    14  <img src="https://netdata.cloud/img/network-wired.svg" width="150"/>
    15  
    16  
    17  Plugin: go.d.plugin
    18  Module: dns_query
    19  
    20  <img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />
    21  
    22  ## Overview
    23  
    24  This module monitors DNS query round-trip time (RTT).
    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 server
    58  
    59  These metrics refer to the DNS server.
    60  
    61  Labels:
    62  
    63  | Label      | Description     |
    64  |:-----------|:----------------|
    65  | server | DNS server address. |
    66  | network | Network protocol name (tcp, udp, tcp-tls). |
    67  | record_type | DNS record type (e.g. A, AAAA, CNAME). |
    68  
    69  Metrics:
    70  
    71  | Metric | Dimensions | Unit |
    72  |:------|:----------|:----|
    73  | dns_query.query_status | success, network_error, dns_error | status |
    74  | dns_query.query_time | query_time | seconds |
    75  
    76  
    77  
    78  ## Alerts
    79  
    80  
    81  The following alerts are available:
    82  
    83  | Alert name  | On metric | Description |
    84  |:------------|:----------|:------------|
    85  | [ dns_query_query_status ](https://github.com/netdata/netdata/blob/master/health/health.d/dns_query.conf) | dns_query.query_status | DNS request type ${label:record_type} to server ${label:server} is unsuccessful |
    86  
    87  
    88  ## Setup
    89  
    90  ### Prerequisites
    91  
    92  No action required.
    93  
    94  ### Configuration
    95  
    96  #### File
    97  
    98  The configuration file name for this integration is `go.d/dns_query.conf`.
    99  
   100  
   101  You can edit the configuration file using the `edit-config` script from the
   102  Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#the-netdata-config-directory).
   103  
   104  ```bash
   105  cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
   106  sudo ./edit-config go.d/dns_query.conf
   107  ```
   108  #### Options
   109  
   110  The following options can be defined globally: update_every, autodetection_retry.
   111  
   112  
   113  <details><summary>All options</summary>
   114  
   115  | Name | Description | Default | Required |
   116  |:----|:-----------|:-------|:--------:|
   117  | update_every | Data collection frequency. | 1 | no |
   118  | autodetection_retry | Recheck interval in seconds. Zero means no recheck will be scheduled. | 0 | no |
   119  | domains | Domain or subdomains to query. The collector will choose a random domain from the list on every iteration. |  | yes |
   120  | servers | Servers to query. |  | yes |
   121  | port | DNS server port. | 53 | no |
   122  | network | Network protocol name. Available options: udp, tcp, tcp-tls. | udp | no |
   123  | record_types | Query record type. Available options: A, AAAA, CNAME, MX, NS, PTR, TXT, SOA, SPF, TXT, SRV. | A | no |
   124  | timeout | Query read timeout. | 2 | no |
   125  
   126  </details>
   127  
   128  #### Examples
   129  
   130  ##### Basic
   131  
   132  An example configuration.
   133  
   134  <details><summary>Config</summary>
   135  
   136  ```yaml
   137  jobs:
   138    - name: job1
   139      record_types:
   140        - A
   141        - AAAA
   142      domains:
   143        - google.com
   144        - github.com
   145        - reddit.com
   146      servers:
   147        - 8.8.8.8
   148        - 8.8.4.4
   149  
   150  ```
   151  </details>
   152  
   153  
   154  
   155  ## Troubleshooting
   156  
   157  ### Debug Mode
   158  
   159  To troubleshoot issues with the `dns_query` collector, run the `go.d.plugin` with the debug option enabled. The output
   160  should give you clues as to why the collector isn't working.
   161  
   162  - Navigate to the `plugins.d` directory, usually at `/usr/libexec/netdata/plugins.d/`. If that's not the case on
   163    your system, open `netdata.conf` and look for the `plugins` setting under `[directories]`.
   164  
   165    ```bash
   166    cd /usr/libexec/netdata/plugins.d/
   167    ```
   168  
   169  - Switch to the `netdata` user.
   170  
   171    ```bash
   172    sudo -u netdata -s
   173    ```
   174  
   175  - Run the `go.d.plugin` to debug the collector:
   176  
   177    ```bash
   178    ./go.d.plugin -d -m dns_query
   179    ```
   180  
   181