{"id":30876372,"url":"https://github.com/telekom/sparrow","last_synced_at":"2025-09-08T02:09:31.196Z","repository":{"id":209615906,"uuid":"706172212","full_name":"telekom/sparrow","owner":"telekom","description":"A monitoring tool to gather infrastructure network information","archived":false,"fork":false,"pushed_at":"2025-09-01T19:47:16.000Z","size":1549,"stargazers_count":21,"open_issues_count":10,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-01T21:25:26.758Z","etag":null,"topics":["infrastructure","monitoring","network","observability","sparrow"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/telekom.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-10-17T12:47:45.000Z","updated_at":"2025-09-01T19:42:08.000Z","dependencies_parsed_at":"2023-11-28T10:27:49.391Z","dependency_job_id":"7b7d6a14-10a2-46b9-8d6c-fc950de71a8f","html_url":"https://github.com/telekom/sparrow","commit_stats":{"total_commits":168,"total_committers":6,"mean_commits":28.0,"dds":0.6011904761904762,"last_synced_commit":"9f1d0d34430079c777b4513de6e02250e5131eb7"},"previous_names":["caas-team/sparrow","telekom/sparrow"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/telekom/sparrow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telekom%2Fsparrow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telekom%2Fsparrow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telekom%2Fsparrow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telekom%2Fsparrow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/telekom","download_url":"https://codeload.github.com/telekom/sparrow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telekom%2Fsparrow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274121957,"owners_count":25225801,"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","status":"online","status_checked_at":"2025-09-08T02:00:09.813Z","response_time":121,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["infrastructure","monitoring","network","observability","sparrow"],"created_at":"2025-09-08T02:09:26.895Z","updated_at":"2025-09-08T02:09:31.182Z","avatar_url":"https://github.com/telekom.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\nSPDX-FileCopyrightText: 2025 Deutsche Telekom IT GmbH\n\nSPDX-License-Identifier: CC-BY-4.0\n--\u003e\n\n# Sparrow - Infrastructure Monitoring\u003c!-- omit from toc --\u003e\n\n\u003c!-- markdownlint-disable MD033 --\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"/../../commits/\" title=\"Last Commit\"\u003e\u003cimg alt=\"Last Commit\" src=\"https://img.shields.io/github/last-commit/telekom/sparrow?style=flat\"\u003e\u003c/a\u003e\n  \u003ca href=\"/../../issues\" title=\"Open Issues\"\u003e\u003cimg alt=\"Open Issues\" src=\"https://img.shields.io/github/issues/telekom/sparrow?style=flat\"\u003e\u003c/a\u003e\n  \u003ca href=\"./LICENSE\" title=\"License\"\u003e\u003cimg alt=\"License\" src=\"https://img.shields.io/badge/License-Apache%202.0-green.svg?style=flat\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003c!-- markdownlint-enable MD033 --\u003e\n\n- [About this component](#about-this-component)\n- [Installation](#installation)\n  - [Binary](#binary)\n  - [Container Image](#container-image)\n  - [Helm](#helm)\n- [Usage](#usage)\n  - [Image](#image)\n- [Configuration](#configuration)\n  - [Startup](#startup)\n    - [Example Startup Configuration](#example-startup-configuration)\n    - [Loader](#loader)\n    - [Logging Configuration](#logging-configuration)\n  - [Checks](#checks)\n  - [Target Manager](#target-manager)\n  - [Check: Health](#check-health)\n    - [Example configuration](#example-configuration)\n    - [Health Metrics](#health-metrics)\n  - [Check: Latency](#check-latency)\n    - [Example configuration](#example-configuration-1)\n    - [Latency Metrics](#latency-metrics)\n  - [Check: DNS](#check-dns)\n    - [Example configuration](#example-configuration-2)\n    - [DNS Metrics](#dns-metrics)\n  - [Check: Traceroute](#check-traceroute)\n    - [Example configuration](#example-configuration-3)\n    - [Optional Capabilities](#optional-capabilities)\n    - [Traceroute Prometheus Metrics](#traceroute-prometheus-metrics)\n    - [Traceroute API Metrics](#traceroute-api-metrics)\n- [API](#api)\n- [Metrics, Telemetry \\\u0026 Dashboards](#metrics-telemetry--dashboards)\n  - [Prometheus Integration](#prometheus-integration)\n  - [Traces](#traces)\n  - [Grafana Dashboards](#grafana-dashboards)\n- [Code of Conduct](#code-of-conduct)\n- [Working Language](#working-language)\n- [Support and Feedback](#support-and-feedback)\n- [How to Contribute](#how-to-contribute)\n- [Licensing](#licensing)\n\nThe `sparrow` is an infrastructure monitoring tool. The binary includes several checks (e.g. health check) that will be\nexecuted periodically.\n\n## About this component\n\nThe `sparrow` performs several checks to monitor the health of the infrastructure and network from its point of view.\nThe following checks are available:\n\n1. [Health check](#check-health) - `health`: The `sparrow` is able to perform an HTTP-based (HTTP/1.1) health check to\n   the provided endpoints. The `sparrow` will expose its own health check endpoint as well.\n\n2. [Latency check](#check-latency) - `latency`: The `sparrow` is able to communicate with other `sparrow` instances to\n   calculate the time a request takes to the target and back. The check is http (HTTP/1.1) based as well.\n\n3. [DNS check](#check-dns) - `dns`: The `sparrow` is able to perform DNS resolution checks to monitor domain name system\n   performance and reliability. The check has the ability to target specific domains or IPs for monitoring.\n\n4. [Traceroute Check](#check-traceroute) - `traceroute`: The `sparrow` is able to perform traceroute checks to monitor\n   the network path to a target. The check has the ability to target specific domains or IPs for monitoring.\n\nEach check is designed to provide comprehensive insights into the various aspects of network and service health,\nensuring robust monitoring and quick detection of potential issues.\n\n## Installation\n\nThe `sparrow` is provided as a small binary \u0026 a container image.\n\nPlease refer to the [release notes](https://github.com/telekom/sparrow/releases) to get the latest version.\n\n### Binary\n\nThe binary is available for several distributions. To install the binary, use a provided bundle or source.\nReplace `${RELEASE_VERSION}` with the desired release version:\n\n```sh\nexport RELEASE_VERSION=0.5.0\n```\n\nDownload the binary:\n\n```sh\ncurl https://github.com/telekom/sparrow/releases/download/v${RELEASE_VERSION}/sparrow_${RELEASE_VERSION}_linux_amd64.tar.gz -Lo sparrow.tar.gz\ncurl https://github.com/telekom/sparrow/releases/download/v${RELEASE_VERSION}/sparrow_${RELEASE_VERSION}_checksums.txt -Lo checksums.txt\n```\n\nExtract the binary:\n\n```sh\ntar -xf sparrow.tar.gz\n```\n\n### Container Image\n\nThe [sparrow container images](https://github.com/telekom/sparrow/pkgs/container/sparrow) for\ndedicated [release](https://github.com/telekom/sparrow/releases) can be found in the GitHub registry.\n\n### Helm\n\nSparrow can be installed via Helm Chart. The chart is available in the GitHub registry:\n\n```sh\nhelm -n sparrow upgrade -i sparrow oci://ghcr.io/telekom/charts/sparrow --create-namespace\n```\n\nThe default settings are suitable for a local configuration. With the default Helm values, the sparrow loader uses a\nchecks' configuration provided in a ConfigMap (the `file` loader is used). Define the `checksConfig` section to set the\nConfigMap.\n\nUse the following configuration values to use a runtime configuration by the `http` loader:\n\n```yaml\nstartupConfig:\n  ...\n  loader:\n    type: http\n    interval: 30s\n    http:\n      url: https://url-to-checks-config.de/api/config%2Eyaml\n\nchecksConfig: { }\n```\n\nTo provide the sparrow container with the token, manually create a secret containing the `SPARROW_LOADER_HTTP_TOKEN`\nenvironment variable. Utilize the `envFromSecrets` in the `values.yaml` to enable access to this secret by the sparrow\ncontainer. Avoid adding sensitive data like the token used by the `http` loader (`loader.http.token`) directly in the\nvalues section.\n\nThe same applies to the target manager token. Use the `SPARROW_TARGETMANAGER_GITLAB_TOKEN` in a secret and bind it with\nthe `envFromSecrets` in the `values.yaml`.\n\nFor all available value options see [Chart README](./chart/README.md).\n\nAdditionally check out the sparrow [configuration](#configuration) variants.\n\n## Usage\n\nUse `sparrow run` to execute the instance using the binary. A `sparrowName` (a valid DNS name) is required to be passed,\nelse the sparrow will not start:\n\n```sh\nsparrow run --sparrowName sparrow.telekom.de\n```\n\n### Image\n\nRun a `sparrow` container by using e.g. `docker run ghcr.io/telekom/sparrow`.\n\nPass the available configuration arguments to the container e.g. `docker run ghcr.io/telekom/sparrow --help`.\n\nStart the instance using a mounted startup configuration file\ne.g. `docker run -v /config:/config  ghcr.io/telekom/sparrow --config /config/config.yaml`.\n\n## Configuration\n\nThe configuration is divided into two parts. The startup configuration and the checks' configuration. The startup\nconfiguration is a technical configuration to configure the `sparrow` instance itself.\n\n### Startup\n\nThe available configuration options can be found in the [CLI flag documentation](docs/sparrow.md).\n\nThe `sparrow` is able to get the startup configuration from different sources as follows.\n\nPriority of configuration (high to low):\n\n1. CLI flags\n2. Environment variables\n3. Defined configuration file\n4. Default configuration file\n\nEvery value in the config file can be set through environment variables.\n\nYou can set a token for the http loader:\n\n```bash\nexport SPARROW_LOADER_HTTP_TOKEN=\"xxxxxx\"\n```\n\nOr for any other config attribute:\n\n```bash\nexport SPARROW_ANY_OTHER_OPTION=\"Some value\"\n```\n\nJust write out the path to the attribute, delimited by `_`.\n\n#### Example Startup Configuration\n\n```yaml\n# DNS sparrow is exposed on \nname: sparrow.example.com\n\n# Selects and configures a loader to continuously fetch the checks' configuration at runtime\nloader:\n  # Defines which loader to use. Options: \"file | http\"\n  type: http\n  # The interval in which sparrow tries to fetch a new configuration\n  # If this isn't set or set to 0, the loader will only retrieve the configuration once\n  interval: 30s\n  # Config specific to the http loader\n  http:\n    # The URL where the config is located\n    url: https://myconfig.example.com/config.yaml\n    # This token is passed in the Authorization header when refreshing the config\n    token: xxxxxxx\n    # A timeout for the config refresh\n    timeout: 30s\n    retry:\n      # How long to wait in between retries\n      delay: 10s\n      # How many times to retry\n      count: 3\n\n  # Config specific to the file loader\n  # The file loader is not intended for production use\n  file:\n    # Location of the file in the local filesystem\n    path: ./config.yaml\n\n# Configures the API\napi:\n  # Which address to expose Sparrow's REST API on\n  address: :8080\n  # Configures tls for the http server\n  # including prometheus metrics etc\n  tls:\n    # whether to enable tls, default is false\n    enabled: true\n    # path to your x509 certificate\n    certPath: mycert.pem\n    # path to your certificate key\n    keyPath: mykey.key\n\n\n# Configures the target manager.\ntargetManager:\n  # whether to enable the target manager. (default: false)\n  enabled: true\n  # Defines which target manager to use.\n  type: gitlab\n  # The interval for the target reconciliation process\n  checkInterval: 1m\n  # How often the instance should register itself as a global target\n  # A duration of 0 means no registration\n  registrationInterval: 1m\n  # How often the instance should update its registration as a global target\n  # A duration of 0 means no update\n  updateInterval: 120m\n  # The amount of time a target can be unhealthy\n  # before it is removed from the global target list\n  # A duration of 0 means no removal\n  unhealthyThreshold: 360m\n  # Scheme defines with which scheme sparrow should register itself\n  scheme: http\n  # Configuration options for the GitLab target manager\n  gitlab:\n    # The URL of your GitLab host\n    baseUrl: https://gitlab.com\n    # Your GitLab API token\n    # You can also set this value through the SPARROW_TARGETMANAGER_GITLAB_TOKEN environment variable\n    token: glpat-xxxxxxxx\n    # The ID of your GitLab project. This is where Sparrow will register itself\n    # and grab the list of other Sparrows from\n    projectId: 18923\n    # The branch to use for the state file\n    # If not set, it tries to resolve the default branch otherwise it uses the 'main' branch\n    branch: main\n\n# Configures the telemetry exporter.\ntelemetry:\n  # Whether to enable telemetry. (default: false)\n  enabled: true\n  # The telemetry exporter to use.\n  # Options:\n  # grpc: Exports telemetry using OTLP via gRPC.\n  # http: Exports telemetry using OTLP via HTTP.\n  # stdout: Prints telemetry to stdout.\n  # noop | \"\": Disables telemetry.\n  exporter: grpc\n  # The address to export telemetry to.\n  url: localhost:4317\n  # The token to use for authentication.\n  # If the exporter does not require a token, this can be left empty.\n  token: \"\"\n  # Configures tls for the telemetry exporter\n  tls:\n    # Enable or disable TLS\n    enabled: true\n    # The path to the tls certificate to use.\n    # Only required if your otel endpoint uses custom TLS certificates\n    certPath: \"\"\n```\n\n#### Loader\n\nThe loader component of the `sparrow` dynamically loads the [checks](#checks)' configuration during runtime.\n\nYou select which loader is used by setting the `loaderType` parameter.\n\nAvailable loaders:\n\n- `http` (default): Retrieves the checks' configuration from a remote endpoint during runtime. Additional configuration\n  parameters are set in the `loader.http` section.\n\n- `file`: Loads the checks' configuration from a local file during runtime. Additional configuration\n  parameters are set in the `loader.file` section.\n\nIf you want to retrieve the checks' configuration only once, you can set `loader.interval` to 0.\nThe target manager is currently not functional in combination with this configuration.\n\n#### Logging Configuration\n\nYou can configure the logging behavior of the sparrow instance by setting the following environment variables:\n\n- `LOG_LEVEL`: Adjusts the minimum log level.\n  Available options: `DEBUG`, `INFO`, `WARNING`, `ERROR`.\n- `LOG_FORMAT`: Sets the log format. This allows you to customize the format of the log messages.\n  Available options: `JSON`, `TEXT`.\n\n### Checks\n\nIn addition to the technical startup configuration, the `sparrow` checks' configuration can be dynamically loaded during runtime.\nThe `loader` is capable of dynamically loading and configuring checks.\n\nFor detailed information on available loader configuration options, please refer\nto [this documentation](docs/sparrow_run.md).\n\nExample format of a configuration file for the checks:\n\n```YAML\nhealth:\n  targets: [ ]\n```\n\n### Target Manager\n\nThe `sparrow` can optionally manage targets for checks and register itself as a target on a (remote) backend through\nthe `TargetManager` interface. This feature is optional; if the startup configuration does not include\nthe `targetManager`, it will not be used. When configured, it offers various settings, detailed below, which can be set\nin the startup YAML configuration file as shown in the [example configuration](#example-startup-configuration).\n\n| Type                                 | Description                                                                                                                                     |\n| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |\n| `targetManager.enabled`              | Whether to enable the target manager. Defaults to false                                                                                         |\n| `targetManager.type`                 | Type of the target manager. Options: `gitlab`                                                                                                   |\n| `targetManager.scheme`               | Should the target register itself as http or https. Can be `http` or `https`. This needs to be set to `https`, when `api.tls.enabled` == `true` |\n| `targetManager.checkInterval`        | Interval for checking new targets.                                                                                                              |\n| `targetManager.unhealthyThreshold`   | Threshold for marking a target as unhealthy. 0 means no cleanup.                                                                                |\n| `targetManager.registrationInterval` | Interval for registering the current sparrow at the target backend. 0 means no registration.                                                    |\n| `targetManager.updateInterval`       | Interval for updating the registration of the current sparrow. 0 means no update.                                                               |\n| `targetManager.gitlab.baseUrl`       | Base URL of the GitLab instance.                                                                                                                |\n| `targetManager.gitlab.token`         | Token for authenticating with the GitLab instance.                                                                                              |\n| `targetManager.gitlab.projectId`     | Project ID for the GitLab project used as a remote state backend.                                                                               |\n| `targetManager.gitlab.branch`        | Branch to use for the state file. If not set, it tries to resolve the default branch otherwise it uses the `main` branch.                       |\n\nCurrently, only one target manager exists: the Gitlab target manager. It uses a gitlab project as the remote state\nbackend. The various `sparrow` instances can register themselves as targets in the project.\nThe `sparrow` instances will also check the project for new targets and add them to the local state.\nThe registration is done by committing a \"state\" file in the main branch of the repository,\nwhich is named after the DNS name of the `sparrow`. The state file contains the following information:\n\n```json\n{\n  \"url\": \"\u003cSCHEME\u003e://\u003cSPARROW_DNS_NAME\u003e\",\n  \"lastSeen\": \"2021-09-30T12:00:00Z\"\n}\n```\n\n### Check: Health\n\nAvailable configuration options:\n\n| Field         | Type              | Description                                                                                                                                                 |\n| ------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `interval`    | `duration`        | Interval to perform the health check.                                                                                                                       |\n| `timeout`     | `duration`        | Timeout for the health check.                                                                                                                               |\n| `retry.count` | `integer`         | Number of retries for the health check.                                                                                                                     |\n| `retry.delay` | `duration`        | Initial delay between retries for the health check.                                                                                                         |\n| `targets`     | `list of strings` | List of targets to send health probe. Needs to be a valid URL. Can be another `sparrow` instance. Automatically updated when a targetManager is configured. |\n\n#### Example configuration\n\n```yaml\nhealth:\n  interval: 10s\n  timeout: 30s\n  retry:\n    count: 3\n    delay: 1s\n  targets:\n    - https://example.com/\n    - https://google.com/\n```\n\n#### Health Metrics\n\n- `sparrow_health_up`\n  - Type: Gauge\n  - Description: Health of targets\n  - Labelled with `target`\n\n### Check: Latency\n\nAvailable configuration options:\n\n| Field         | Type              | Description                                                                                                                                                  |\n| ------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `interval`    | `duration`        | Interval to perform the latency check.                                                                                                                       |\n| `timeout`     | `duration`        | Timeout for the latency check.                                                                                                                               |\n| `retry.count` | `integer`         | Number of retries for the latency check.                                                                                                                     |\n| `retry.delay` | `duration`        | Initial delay between retries for the latency check.                                                                                                         |\n| `targets`     | `list of strings` | List of targets to send latency probe. Needs to be a valid URL. Can be another `sparrow` instance. Automatically updated when a targetManager is configured. |\n\n\u003c!-- markdownlint-disable MD024 --\u003e\n#### Example configuration\n\u003c!-- markdownlint-enable MD024 --\u003e\n\n```yaml\nlatency:\n  interval: 10s\n  timeout: 30s\n  retry:\n    count: 3\n    delay: 1s\n  targets:\n    - https://example.com/\n    - https://google.com/\n```\n\n#### Latency Metrics\n\n- `sparrow_latency_duration_seconds`\n  - Type: Gauge\n  - Description: Latency with status information of targets. This metric is DEPRECATED. Use `sparrow_latency_seconds`.\n  - Labelled with `target` and `status`\n\n- `sparrow_latency_seconds`\n  - Type: Gauge\n  - Description: Latency information of targets\n  - Labelled with `target`\n\n- `sparrow_latency_count`\n  - Type: Counter\n  - Description: Count of latency checks done\n  - Labelled with `target`\n\n- `sparrow_latency_duration`\n  - Type: Histogram\n  - Description: Latency of targets in seconds\n  - Labelled with `target`\n\n### Check: DNS\n\u003e [!CAUTION]\n\u003e **Breaking Change:** Starting from version `v0.6.0`, the API returns lowercase keys instead of capitalized keys. Ensure that your code handles this change to avoid issues. \n\nAvailable configuration options:\n\n| Field         | Type              | Description                                                                                                                                               |\n| ------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `interval`    | `duration`        | Interval to perform the DNS check.                                                                                                                        |\n| `timeout`     | `duration`        | Timeout for the DNS check.                                                                                                                                |\n| `retry.count` | `integer`         | Number of retries for the DNS check.                                                                                                                      |\n| `retry.delay` | `duration`        | Initial delay between retries for the DNS check.                                                                                                          |\n| `targets`     | `list of strings` | List of targets to lookup. Needs to be a valid domain or IP. Can be another `sparrow` instance. Automatically updated when a targetManager is configured. |\n\n\u003c!-- markdownlint-disable MD024 --\u003e\n#### Example configuration\n\u003c!-- markdownlint-enable MD024 --\u003e\n\n```yaml\ndns:\n  interval: 10s\n  timeout: 30s\n  retry:\n    count: 3\n    delay: 1s\n  targets:\n    - www.example.com\n    - www.google.com\n```\n\n#### DNS Metrics\n\n- `sparrow_dns_status`\n  - Type: Gauge\n  - Description: Lookup status of targets\n  - Labelled with `target`\n\n- `sparrow_dns_check_count`\n  - Type: Counter\n  - Description: Count of DNS checks done\n  - Labelled with `target`\n\n- `sparrow_dns_duration_seconds`\n  - Type: Gauge\n  - Description: Duration of DNS resolution attempts\n  - Labelled with `target`\n\n- `sparrow_dns_duration`\n  - Type: Histogram\n  - Description: Histogram of response times for DNS checks\n  - Labelled with `target`\n\n### Check: Traceroute\n\n| Field            | Type              | Description                                                                  |\n| ---------------- | ----------------- | ---------------------------------------------------------------------------- |\n| `interval`       | `duration`        | Interval to perform the Traceroute check.                                    |\n| `timeout`        | `duration`        | Timeout for every hop.                                                       |\n| `retry.count`    | `integer`         | Number of retries for the latency check.                                     |\n| `retry.delay`    | `duration`        | Initial delay between retries for the latency check.                         |\n| `maxHops`        | `integer`         | Maximum number of hops to try before giving up.                              |\n| `targets`        | `list of objects` | List of targets to traceroute to.                                            |\n| `targets[].addr` | `string`          | The address of the target to traceroute to. Can be an IP address or DNS name |\n| `targets[].port` | `uint16`          | The port of the target to traceroute to. Default is 80                       |\n\n\u003c!-- markdownlint-disable MD024 --\u003e\n#### Example configuration\n\u003c!-- markdownlint-enable MD024 --\u003e\n\n```yaml\ntraceroute:\n  interval: 5s\n  timeout: 3s\n  retry:\n    count: 3\n    delay: 1s\n  maxHops: 30\n  targets:\n    - addr: 8.8.8.8\n      port: 53\n    - addr: www.google.com\n      port: 80\n```\n\n#### Optional Capabilities\n\nSparrow does not need any extra permissions to run this check. However, some data, like the ip address\nof the hop that dropped a packet, will not be available. To enable this functionality, there are two options:\n\n- Run sparrow as root:\n\n  ```bash\n  sudo sparrow run --config config.yaml\n  ```\n\n- Allow sparrow to create raw sockets, by assigning the `CAP_NET_RAW` capability to the sparrow binary:\n\n  ```bash\n  sudo setcap 'cap_net_raw=ep' sparrow\n  ```\n\n#### Traceroute Prometheus Metrics\n\n- `sparrow_traceroute_check_duration_ms{target=\"google.com\"} 43150`\n  - Type: Gauge\n  - Description: How long the last traceroute took for this target in total\n- `sparrow_traceroute_minimum_hops{target=\"google.com\"} 14`\n  - Type: Gauge\n  - Description: The minimum number of hops required to reach a target\n\n#### Traceroute API Metrics\n\nThe traceroute check exposes additional data through its rest API that isn't available in prometheus.\nThis data give a more detailed breakdown of the trace and can be found at `/v1/metrics/traceroute` and is\nmeant to be a json representation of traditional traceroute output:\n\n```bash\n$ traceroute -T -q 1 100.1.2.2\n 1  200.2.0.1 (200.2.0.1)  2 ms\n 2  11.0.0.34 (11.0.0.34)  5 ms\n ...\n```\n\nIs roughly equal to this:\n\n```json\n{\n  \"data\": {\n    \"100.1.2.2\": {\n      \"MinHops\": 1,\n      \"Hops\": {\n        \"1\": [\n          {\n            \"Latency\": 2,\n            \"Addr\": {\n              \"IP\": \"200.2.0.1\",\n              \"Port\": 80,\n              \"Zone\": \"\"\n            },\n            \"Name\": \"\",\n            \"Ttl\": 1,\n            \"Reached\": false\n          }\n        ],\n        \"2\": [\n          {\n            \"Latency\": 5,\n            \"Addr\": {\n              \"IP\": \"11.0.0.34\",\n              \"Port\": 80,\n              \"Zone\": \"\"\n            },\n            \"Name\": \"\",\n            \"Ttl\": 2,\n            \"Reached\": false\n          }\n        ]\n        ...\n      }\n    },\n  },\n  \"timestamp\": \"2024-07-26T15:49:39.60760766+02:00\"\n}\n\n```\n\n## API\n\n\u003e [!CAUTION]\n\u003e **Breaking Change:** Starting from version `v0.6.0`, the API returns lowercase keys instead of capitalized keys. Ensure that your code handles this change to avoid issues.\n\nThe `sparrow` exposes an API for accessing the results of various checks. Each check registers its own endpoint\nat `/v1/metrics/{check-name}`. The API's definition is available at `/openapi`.\n\n## Metrics, Telemetry \u0026 Dashboards\n\nThe `sparrow` provides a `/metrics` endpoint to expose application metrics. In addition to runtime information, the sparrow provides specific metrics for each check. Refer to the [Checks](#checks) section for more detailed information.\n\n### Prometheus Integration\n\nThe `sparrow` metrics API is designed to be compatible with Prometheus. To integrate `sparrow` with Prometheus, add the following scrape configuration to your Prometheus configuration file:\n\n```yaml\nscrape_configs:\n  - job_name: 'sparrow'\n    static_configs:\n      - targets: ['\u003csparrow_instance_address\u003e:8080']\n```\n\nReplace `\u003csparrow_instance_address\u003e` with the actual address of your `sparrow` instance.\n\n### Traces\n\nThe `sparrow` supports exporting telemetry data using the OpenTelemetry Protocol (OTLP). This allows users to choose their preferred telemetry provider and collector. The following configuration options are available for setting up telemetry:\n\n| Field          | Type     | Description                                                                 |\n| -------------- | -------- | --------------------------------------------------------------------------- |\n| `enabled`      | `bool`   | Whether to enable telemetry. Default: `false`                               |\n| `exporter`     | `string` | The telemetry exporter to use. Options: `grpc`, `http`, `stdout`, `noop`    |\n| `url`          | `string` | The address to export telemetry to.                                         |\n| `token`        | `string` | The token to use for authentication.                                        |\n| `tls.enabled`  | `bool`   | Enable or disable TLS.                                                      |\n| `tls.certPath` | `string` | The path to the TLS certificate to use. Only required if custom TLS is used |\n\nFor example, to export telemetry data using OTLP via gRPC, you can add the following configuration to your [startup configuration](#startup):\n\n```yaml\ntelemetry:\n  # Whether to enable telemetry. (default: false)\n  enabled: true\n  # The telemetry exporter to use.\n  # Options:\n  # grpc: Exports telemetry using OTLP via gRPC.\n  # http: Exports telemetry using OTLP via HTTP.\n  # stdout: Prints telemetry to stdout.\n  # noop | \"\": Disables telemetry.\n  exporter: grpc\n  # The address to export telemetry to.\n  url: collector.example.com:4317\n  # The token to use for authentication.\n  # If the exporter does not require a token, this can be left empty.\n  token: \"\"\n  tls:\n    # Enable or disable TLS\n    enabled: true\n    # The path to the tls certificate to use.\n    # Only required if your otel endpoint uses custom TLS certificates\n    certPath: \"\"\n```\n\nSince [OTLP](https://opentelemetry.io/docs/specs/otlp/) is a standard protocol, you can choose any collector that supports it. The `stdout` exporter can be used for debugging purposes to print telemetry data to the console, while the `noop` exporter disables telemetry. If an external collector is used, a bearer token for authentication and a TLS certificate path for secure communication can be provided.\n\n### Grafana Dashboards\n\nA sample Grafana dashboard to visualize the metrics collected by the checks is available in the `examples` directory of the repository. How to import dashboards into Grafana is documented [here](https://grafana.com/docs/grafana/latest/reference/export_import/).\n\n\u003cimg src=\"examples/dashboard.png\"\u003e\n\n## Code of Conduct\n\nThis project has adopted the [Contributor Covenant](https://www.contributor-covenant.org/) in version 2.1 as our code of\nconduct. Please see the details in our [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). All contributors must abide by the code\nof conduct.\n\nBy participating in this project, you agree to abide by its [Code of Conduct](CODE_OF_CONDUCT.md) at all times.\n\n## Working Language\n\nWe decided to apply *English* as the primary project language.\n\nConsequently, all content will be made available primarily in English.\nWe also ask all interested people to use English as the preferred language to create issues,\nin their code (comments, documentation, etc.) and when you send requests to us.\nThe application itself and all end-user facing content will be made available in other languages as needed.\n\n## Support and Feedback\n\nThe following channels are available for discussions, feedback, and support requests:\n\n\u003c!-- markdownlint-disable MD033 --\u003e\n| Type       | Channel                                                                                                                                                           |\n| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Issues** | \u003ca href=\"/../../issues/new/choose\" title=\"General Discussion\"\u003e\u003cimg alt=\"Issues\" src=\"https://img.shields.io/github/issues/telekom/sparrow?style=flat-square\"\u003e\u003c/a\u003e |\n\u003c!-- markdownlint-enable MD033 --\u003e\n\n## How to Contribute\n\nContribution and feedback is encouraged and always welcome. For more information about how to contribute, the project\nstructure, as well as additional contribution information, see our [Contribution Guidelines](./CONTRIBUTING.md). By\nparticipating in this project, you agree to abide by its [Code of Conduct](./CODE_OF_CONDUCT.md) at all times.\n\n## Licensing\n\nThis project follows the [REUSE standard for software licensing](https://reuse.software/).\nEach file contains copyright and license information, and license texts can be found in the [./LICENSES](./LICENSES) folder. For more information visit https://reuse.software/.\nYou can find a guide for developers at [Reuse Template Docs](https://telekom.github.io/reuse-template/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelekom%2Fsparrow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftelekom%2Fsparrow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelekom%2Fsparrow/lists"}