effectivelywild.technitium_dns.technitium_dns_get_stats module – Get DNS statistics from server dashboard

Note

This module is part of the effectivelywild.technitium_dns collection (version 1.1.2).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install effectivelywild.technitium_dns.

To use it in a playbook, specify: effectivelywild.technitium_dns.technitium_dns_get_stats.

New in effectivelywild.technitium_dns 0.8.0

Synopsis

• Retrieve DNS statistics displayed on the server dashboard.

• Returns aggregate stats, chart data, and top lists for clients, domains, and blocked domains.

Parameters

Parameter	Comments
api_port integer	Port for the Technitium DNS API. Defaults to 5380 Default: 5380
api_token string / required	API token for authenticating with the Technitium DNS API
api_url string / required	Base URL for the Technitium DNS API
end string	End date in ISO 8601 format. Only applies to ‘Custom’ type.
node string	The node domain name for which the stats data is needed When unspecified, the current node is used Set node name as ‘cluster’ to get aggregate stats for the entire cluster This parameter can be used only when Clustering is initialized
start string	Start date in ISO 8601 format. Only applies to ‘Custom’ type.
type string	The duration type for statistics. Choices: "LastHour" ← (default) "LastDay" "LastWeek" "LastMonth" "LastYear" "Custom"
utc boolean	Set to true to return chart data with labels in UTC format. Choices: false ← (default) true
validate_certs boolean	Whether to validate SSL certificates when making API requests. Choices: false true ← (default)

See Also

See also

effectivelywild.technitium_dns.technitium_dns_get_top_stats

Get top statistics for specific stats type

effectivelywild.technitium_dns.technitium_dns_delete_all_stats

Delete all statistics from the server

Examples

- name: Get last hour statistics
  technitium_dns_get_stats:
    api_url: "http://localhost"
    api_token: "myapitoken"
  register: result

- name: Get last day statistics in UTC
  technitium_dns_get_stats:
    api_url: "http://localhost"
    api_token: "myapitoken"
    type: "LastDay"
    utc: true
  register: result

- name: Get custom date range statistics
  technitium_dns_get_stats:
    api_url: "http://localhost"
    api_token: "myapitoken"
    type: "Custom"
    start: "2024-01-01T00:00:00Z"
    end: "2024-01-31T23:59:59Z"
  register: result

- name: Get cluster-wide statistics
  technitium_dns_get_stats:
    api_url: "http://localhost"
    api_token: "myapitoken"
    node: "cluster"
  register: result

- name: Get statistics for specific node
  technitium_dns_get_stats:
    api_url: "http://localhost"
    api_token: "myapitoken"
    node: "node1.example.com"
  register: result

- debug:
    var: result.stats

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
changed boolean	Whether the module made changes (always false for get operations) Returned: always Sample: false
failed boolean	Whether the module failed Returned: always Sample: false
mainChartData dictionary	Main chart data with time series Returned: always
datasets list / elements=dictionary	Chart datasets for different metrics Returned: always
labelFormat string	Format for time labels Returned: always Sample: "HH:mm"
labels list / elements=string	Array of timestamp labels Returned: always
protocolTypeChartData dictionary	Protocol type distribution chart data Returned: always
datasets list / elements=dictionary	Protocol count datasets Returned: always
labels list / elements=string	Protocol labels (UDP, TCP, etc.) Returned: always
queryResponseChartData dictionary	Query response type distribution chart data Returned: always
datasets list / elements=dictionary	Response count datasets Returned: always
labels list / elements=string	Response type labels Returned: always
queryTypeChartData dictionary	Query type distribution chart data Returned: always
datasets list / elements=dictionary	Query count datasets Returned: always
labels list / elements=string	Query type labels (A, AAAA, HTTPS, etc.) Returned: always
stats dictionary	Aggregate DNS statistics Returned: always
allowedZones integer	Total allowed zones Returned: always Sample: 10
allowListZones integer	Total allow list zones Returned: always Sample: 0
blockedZones integer	Total blocked zones Returned: always Sample: 1
blockListZones integer	Total block list zones Returned: always Sample: 307447
cachedEntries integer	Total cached entries Returned: always Sample: 6330
totalAuthoritative integer	Total authoritative responses Returned: always Sample: 47
totalBlocked integer	Total blocked queries Returned: always Sample: 49
totalCached integer	Total cached responses Returned: always Sample: 481
totalClients integer	Total unique clients Returned: always Sample: 6
totalDropped integer	Total dropped queries Returned: always Sample: 0
totalNoError integer	Total successful queries Returned: always Sample: 834
totalNxDomain integer	Total non-existent domain responses Returned: always Sample: 90
totalQueries integer	Total number of queries Returned: always Sample: 925
totalRecursive integer	Total recursive queries Returned: always Sample: 348
totalRefused integer	Total refused queries Returned: always Sample: 0
totalServerFailure integer	Total server failure responses Returned: always Sample: 1
zones integer	Total number of zones Returned: always Sample: 19
topBlockedDomains list / elements=dictionary	List of most blocked domains Returned: always
hits integer	Number of blocked queries for this domain Returned: always Sample: 10
name string	Blocked domain name Returned: always Sample: "mobile.pipe.aria.microsoft.com"
topClients list / elements=dictionary	List of top DNS clients Returned: always
domain string	Client hostname (if resolved) Returned: always Sample: "server1.home"
hits integer	Number of queries from this client Returned: always Sample: 463
name string	Client IP address Returned: always Sample: "192.168.10.5"
rateLimited boolean	Whether client is rate limited Returned: always Sample: false
topDomains list / elements=dictionary	List of most queried domains Returned: always
hits integer	Number of queries for this domain Returned: always Sample: 34
name string	Domain name Returned: always Sample: "www.google.com"

Authors

• Frank Muise (@effectivelywild)

Collection links

• Issue Tracker
• Repository (Sources)