{"id":16813389,"url":"https://github.com/maxenglander/dometer","last_synced_at":"2025-03-17T11:24:45.825Z","repository":{"id":147784778,"uuid":"200556204","full_name":"maxenglander/dometer","owner":"maxenglander","description":"dometer is a DNS proxy that emits telemetry","archived":false,"fork":false,"pushed_at":"2020-04-20T07:53:26.000Z","size":34,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-23T20:53:59.084Z","etag":null,"topics":["cpp","dns","dns-proxy","metrics","prometheus","telemetry"],"latest_commit_sha":null,"homepage":"https://github.com/maxenglander/dometer","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maxenglander.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-08-05T00:33:08.000Z","updated_at":"2020-04-20T07:56:04.000Z","dependencies_parsed_at":"2023-05-27T13:00:26.822Z","dependency_job_id":null,"html_url":"https://github.com/maxenglander/dometer","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxenglander%2Fdometer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxenglander%2Fdometer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxenglander%2Fdometer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxenglander%2Fdometer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maxenglander","download_url":"https://codeload.github.com/maxenglander/dometer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244022683,"owners_count":20385137,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpp","dns","dns-proxy","metrics","prometheus","telemetry"],"created_at":"2024-10-13T10:26:32.279Z","updated_at":"2025-03-17T11:24:45.784Z","avatar_url":"https://github.com/maxenglander.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dometer\n\n`dometer` is a DNS proxy that emits telemetry.\n\n## Platforms\n\n`dometer` has been built and tested on the following platforms:\n\n| Platform | Versions |\n| :------- | :------- |\n| Mac OS   | 10.12.6, 10.15.4 |\n| Ubuntu   | 18.04.4  |\n\n## Building\n\nIn order to build `dometer`, the following build-time dependencies are\nrequired and must be either already present or manually installed.\n\n| Dependency | Recommended version |\n| :--------- | :------------------ |\n| Bazel      | 2.2.0               |\n| CMake      | 3.16.2              |\n| envsubst   | 0.20.2              |\n\nVersions other than those recommended above may or may not work.\n\nOnce the build-time dependencies are present, run the following command to build\n`dometer`:\n\n```\ndometer $ bazel build //dometer/cli:main\n```\n\nBazel will download and build the following third-party libraries for run-time use.\n\n * [ThinkAsync/asio (non-Boost version)](http://think-async.com/Asio)\n * [TartanLlama/expected](https://github.com/TartanLlama/expected)\n * [open-source-parsers/openjsoncpp](https://github.com/open-source-parsers/jsoncpp)\n * [jupp0r/prometheus-cpp](https://github.com/jupp0r/prometheus-cpp)\n * [TartanLlama/optional](https://github.com/TartanLlama/optional)\n * [mpark/variant](https://github.com/mpark/variant)\n * [tristanpenman/valijson](https://github.com/tristanpenman/valijson)\n\n## Usage\n\n`dometer` is started through the command-line.\n\n```\ndometer $ ./bazel-bin/dometer/cli/main\nDometer.\n\nUsage:\n  dometer --config=\u003cpath\u003e\n  dometer --help\n\nOptions:\n  --config=\u003cfile\u003e  Supply configuration file [default: /etc/dometer/config.json].\n  --help           Show this help message.\n```\n\nFor example:\n\n```\ndometer $ ./bazel-bin/dometer/cli --config dometer/config/config.json.sample\n```\n\n## Configuration\n\n`dometer` is configured through a JSON file, e.g.:\n\n```\ndometer $ ./bazel-bin/dometer/cli/main --config dometer/config/config.json.sample\n```\n\nSee the [configuration JSON schema](./dometer/config/schema.json) for a description\nof the available options, or the [sample configuration file](./dometer/config/config.json.sample)\nfor an example configuration.\n\n## Components\n\n### DNS\n\nThe `dometer` DNS component accepts and resolves incoming DNS requests.\n\n#### Server\n\nThe `dometer` DNS server listens for incoming UDP DNS requests, by default at\n`udp://0.0.0.0:6353`.\n\n#### Resolver\n\n`dometer` resolves incoming DNS requests using a resolver. The following\nresolver types can be selected:\n\n * `libresolv`\n\nBy default, the `libresolv` resolver is used.\n\n##### `libresolv`\n\nThe `libresolv` resolver library uses the BIND-compatible resolver library native\nto the host platform. It can be configured to use one of the following resolver\nfunctions:\n\n| Function | Description |\n| :------- | :---------- |\n| `query`  | Uses the `res_query(3)` resolver routine. |\n| `search` | Uses the `res_search(3)` resolver routine. |\n\n### Metrics\n\nThe `dometer` metrics component collects metrics on DNS resolution attempts and\nreplies for each incoming DNS request.\n\nThe following metrics are collected:\n\n| Name | Type | Unit | Description |\n| :---- | :---- | :---- | :----------- |\n| `dometer_dns_lookup_duration` | histogram | seconds | The duration of DNS resolutions attempted by `dometer`. |\n\n#### Handlers\n\n`dometer` emits collected metrics using one or more configured handlers.\nCurrently, the following handlers are supported:\n\n * `prometheus`\n\n##### `prometheus`\n\nThe `prometheus` handler emits metrics as Prometheus time-series. By default, it\nexposes metrics through an HTTP server serving requests at `http://0.0.0.0:9090/metrics`.\n\n**Format**\n\nIt emits metric data in the following format:\n\n```\ndometer_dns_lookup_duration_seconds_count{\n  error=\"-|NOERROR|CONNREFUSED|...\",\n  qclass=\"IN\",\n  qname=\".*\",\n  qtype=\"A|MX|...\",\n  rcode=\"-|NOERROR|NXDOMAIN|...\",\n  [additional_labels]\n} \u003ccount\u003e\ndometer_dns_lookup_duration_seconds_sum{\n  error=\"-|NOERROR|CONNREFUSED|...\",\n  qclass=\"IN\",\n  qname=\".*\",\n  qtype=\"A|MX|...\",\n  rcode=\"-|NOERROR|NXDOMAIN|...\",\n  [additional_labels]\n} \u003cseconds\u003e\ndometer_dns_lookup_duration_seconds_bucket{\n  error=\"-|NOERROR|CONNREFUSED|...\",\n  qclass=\"IN\",\n  qname=\".*\",\n  qtype=\"A|MX|...\",\n  rcode=\"-|NOERROR|NXDOMAIN|...\",\n  [additional_labels],\n  le=\"\u003cseconds\u003e\"\n} \u003ccount\u003e\n```\n\n**Maximum time-series**\n\nBecause the possible combinations of domains and record types that can be\nrequested through `dometer` is potentially unbounded, the Prometheus metric\nhandler tracks time-series with an LRU cache. This LRU cache will evict the\nleast recently used time-series when new time-series data would result in the\ncache storing more than the user-defined maximum number of time-series.\n\nA Prometheus time-series is a unique combination of:\n \n  * Time-series name (e.g. `dometer_dns_lookup_duration_bucket`)\n  * A set of labels and their values (e.g. `{error=\"-\",rcode=\"NXDOMAIN\",...}`)\n\nThe following Prometheus time-series are distinct, even though they were\ngenerated or updated by the same DNS request to `dometer`:\n\n```\ndometer_dns_lookup_duration_seconds_bucket{\n  error=\"-\",qclass=\"IN\",qname=\"hello.world\",qtype=\"A\",rcode=\"NXDOMAIN\",le=\"0.1\"\n} 1\ndometer_dns_lookup_duration_seconds_bucket{\n  error=\"-\",qclass=\"IN\",qname=\"hello.world\",qtype=\"A\",rcode=\"NXDOMAIN\",le=\"1.0\"\n} 0\n```\n\nThe number of time-series generated or updated by a single DNS request to\n`dometer` is a function of the metric type and other metric options. For\nexample, a Prometheus histogram metric generates one time series for the total\ncount of collected observations, one for the sum of collected observations, and\none for each each bucket.\n\n## Testing\n\nThe build dependencies listed above must be present in order to test `dometer`.\nOnce they are present, run the following command:\n\n```\ndometer $ bazel test ... \n```\n\nThe following testing libraries will be downloaded and built by Bazel.\n\n * [google/googletest](https://github.com/google/googletest)\n\n## API Stability\n\nNo guarantees are made about the stability of any part of `dometer`, including:\n\n * The name and shape of emitted metrics\n * The command-line interface\n\n## Quality\n\nNo guarantees or assertions are made about the performance, reliability, or\nsafety of this software. Use at your own risk.\n\n## Inspiration and motivation\n\n`dometer` is inspired by Envoy and CoreDNS.\n\n- [Envoy UDP listener](https://www.envoyproxy.io/docs/envoy/latest/configuration/listeners/udp_filters/udp_proxy)\n- [CoreDNS metrics](https://github.com/coredns/coredns/tree/master/plugin/metrics)\n\nI was motivated to create `dometer` as a personal learning project, and because\nI ran into several DNS-related issues at work where a tool like `dometer` would\nhave been useful for debugging.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxenglander%2Fdometer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxenglander%2Fdometer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxenglander%2Fdometer/lists"}