{"id":14483155,"url":"https://github.com/mozilla-services/telescope","last_synced_at":"2025-04-11T13:51:28.381Z","repository":{"id":37005382,"uuid":"202732545","full_name":"mozilla-services/telescope","owner":"mozilla-services","description":"A dumb auditing service ","archived":false,"fork":false,"pushed_at":"2025-04-07T20:54:55.000Z","size":5550,"stargazers_count":21,"open_issues_count":20,"forks_count":8,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-07T21:42:22.061Z","etag":null,"topics":["aiohttp","api","monitoring","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mozilla-services.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-08-16T13:29:01.000Z","updated_at":"2025-04-07T20:54:58.000Z","dependencies_parsed_at":"2023-09-22T06:51:16.941Z","dependency_job_id":"5e39ee8b-3925-43e9-914f-c98e751c481c","html_url":"https://github.com/mozilla-services/telescope","commit_stats":null,"previous_names":[],"tags_count":112,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mozilla-services%2Ftelescope","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mozilla-services%2Ftelescope/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mozilla-services%2Ftelescope/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mozilla-services%2Ftelescope/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mozilla-services","download_url":"https://codeload.github.com/mozilla-services/telescope/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248411951,"owners_count":21099032,"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":["aiohttp","api","monitoring","python"],"created_at":"2024-09-03T00:01:33.726Z","updated_at":"2025-04-11T13:51:28.351Z","avatar_url":"https://github.com/mozilla-services.png","language":"Python","readme":"# Telescope\n\n![Status Sustain](https://img.shields.io/badge/Status-Sustain-green)\n[![CircleCI](https://circleci.com/gh/mozilla-services/telescope.svg?style=svg)](https://circleci.com/gh/mozilla-services/telescope)\n\n*Telescope* is a small Web app that will act as a proxy between a monitoring service — like Pingdom or [Upptime](https://upptime.js.org/) — and a series of domain specific checks for your infrastructure.\n\n\n## Usage\n\nEvery check defined in your configuration file is exposed as an endpoint that returns `200` if successful or `5XX` otherwise:\n\n```http\nGET /checks/{a-project}/{a-check}\n\nHTTP/1.1 200 OK\nContent-Length: 260\nContent-Type: application/json; charset=utf-8\nDate: Fri, 16 Aug 2019 13:29:55 GMT\nServer: Python/3.7 aiohttp/3.5.4\n\n{\n    \"name\": \"a-check\",\n    \"project\": \"a-project\",\n    \"url\": \"/checks/a-project/a-check\",\n    \"module\": \"checks.core.heartbeat\",\n    \"documentation\": \"URL should return a 200 response.\",\n    \"description\": \"Some check description.\",\n    \"success\": true,\n    \"parameters\": {},\n    \"data\": {\n        \"ok\": true\n    }\n}\n\n```\n\nThe response has some additional `\"data\"`, specific to each type of check.\n\nCache can be forced to be refreshed with the ``?refresh={s3cr3t}`` querystring. See *Environment variables* section.\n\n### Other endpoints:\n\n* ``/checks``: list all checks, without executing them.\n* ``/checks/{a-project}``: execute all checks of project ``a-project``\n* ``/checks/tags/{a-tag}``: execute all checks with tag ``a-tag``\n* ``/checks/tags/{tag1}+{tag2}``: execute all checks having both tags ``tag1`` and ``tag2``\n\nOutput format:\n\n* Request header ``Accept: plain/text``: renders the check(s) as a human readable table.\n\n\n## Configure\n\nThe checks are defined in a `config.toml` file, and their module must be available in the current `PYTHONPATH`:\n\n```toml\n[checks.a-project.a-check]\ndescription = \"Heartbeat of the public read-only instance.\"\nmodule = \"checks.core.heartbeat\"\nparams.url = \"https://firefox.settings.services.mozilla.com/v1/__heartbeat__\"\n\n[checks.remotesettings-uptake-release.global-error-rate]\ndescription = \"Global sync status\"\nmodule = \"checks.remotesettings.uptake_error_rate\"\nparams.max_error_percentage = 2\nparams.sources = [\"settings-sync\"]\nparams.channels = [\"release\", \"esr\"]\nparams.period_hours = 3\nttl = 7200\ntags = [\"telemetry\", \"remotesettings\"]\n```\n\n* `description`: Some details about this check\n* `module`: Path to Python module\n* `params`: (*optional*) Parameters specific to the check\n* `ttl`: (*optional*) Cache the check result for a number of seconds\n* `tags`: (*optional*) List of strings allowing grouping of checks at `/tags/{tag}`\n\n\n### Environment variables\n\nThe config file values can refer to environment variables (eg. secrets) using the ``${}`` syntax.\n\n```toml\n[checks.myproject.mycheck]\nmodule = \"checks.remotesettings.collections_consistency\"\nparams.url = \"http://${ENV_NAME}.service.org\"\nparams.auth = \"Bearer ${AUTH}\"\n```\n\n### Server configuration\n\nServer configuration is done via environment variables:\n\n* ``CONFIG_FILE``: Path to configuration file (default: ``\"config.toml\"``)\n* ``CONTACT_EMAIL``: Contact email for this instance (default: ``postmaster@localhost``)\n* ``DIAGRAM_FILE``: Path to SVG diagram file (default: ``\"diagram.svg\"``)\n* ``CORS_ORIGIN``: Allowed requests origins (default: ``*``)\n* ``ENV_NAME``: A string to identify the current environment name like ``\"prod\"`` or ``\"stage\"`` (default: None)\n* ``HOST``: Bind to host (default: ``\"localhost\"``)\n* ``PORT``: Listen on port (default: ``8000``)\n* ``DEFAULT_TTL``: Default TTL for endpoints in seconds (default: ``60``)\n* ``DEFAULT_REQUEST_HEADERS``: Default headers sent in every HTTP requests, as JSON dict format (example: ``{\"Allow-Access\": \"CDN\"}``, default: ``{}``)\n* ``LOG_LEVEL``: One of ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``, ``CRITICAL`` (default: ``INFO``)\n* ``LOG_FORMAT``: Set to ``text`` for human-readable logs (default: ``json``)\n* ``VERSION_FILE``: Path to version JSON file (default: ``\"version.json\"``)\n* ``REFRESH_SECRET``: Secret to allow forcing cache refresh via querystring (default: ``\"\"``)\n* ``REQUESTS_TIMEOUT_SECONDS``: Timeout in seconds for HTTP requests (default: ``5``)\n* ``REQUESTS_MAX_RETRIES``: Number of retries for HTTP requests (default: ``4``)\n* ``SENTRY_DSN``: Report errors to the specified Sentry ``\"https://\u003ckey\u003e@sentry.io/\u003cproject\u003e\"`` (default: disabled)\n* ``SERVICE_NAME``: Name of the running service, used to link known issues in bug tracker (default: ``telescope``)\n* ``SERVICE_TITLE``: Title shown in the UI (default: capitalized service name)\n* ``HISTORY_PROJECT_ID``: ID of GCP project that historic data can be fetched from, should make telescope's logs available through BigQuery (default: None)\n\n* ``BUGTRACKER_URL``: Bug tracker URL. Set to empty string to disable. (default: ``https://bugzilla.mozilla.org``)\n* ``BUGTRACKER_API_KEY``: Bug tracker API key to fetch non-public bugs (default: none)\n* ``BUGTRACKER_TTL``: Default TTL for endpoints in seconds (default: ``3600``)\n\n* ``HISTORY_DAYS``: Number of days to cover whening fetch history of checks (default: 0, disabled)\n* ``HISTORY_TTL``: Default TTL for history refresh in seconds (default: ``3600``)\n\n* ``GITHUB_TOKEN``: Github [Personal Access Token value](https://github.com/settings/tokens) to avoid rate-limiting (default: disabled)\n* ``GOOGLE_APPLICATION_CREDENTIALS``: Absolute path to credentials file for BigQuery authentication (eg. `` `pwd`/key.json``, default: disabled)\n* ``CURL_BINARY_PATH``: path to ``curl`` command (default: ``curl``)\n* ``TROUBLESHOOTING_LINK_TEMPLATE``: Pattern for troubleshooting links, with `{project}` and `{check}` placeholders (default: ``https://wiki.example.com/troubleshooting.html#{project}/{check}``)\n\nConfiguration can be stored in a ``.env`` file:\n\n```\nLOG_LEVEL=debug\n# Disable JSON logs\nLOG_FORMAT=text\n```\n\n## Run Web server\n\nUsing Docker, and a local config file:\n\n```\ndocker run -p 8000:8000 -v `pwd`/config.toml:/app/config.toml mozilla/telescope\n```\n\nOr from source (*requires Python 3.10+ and Poetry*):\n\n```\nmake start\n```\n\n## Web UI\n\nA minimalist Web page is accessible at ``/html/index.html`` and shows every check status,\nalong with the returned data and documentation.\n\nA SVG diagram can be shown in the UI (see ``DIAGRAM_FILE``). Elements of the SVG diagram will be turned red or green based on check results.\nSet the ``id`` attribute of relevant diagram elements to ``${project}--${name}`` (eg. ``remotesettings-uptake--error-rate``) and the app will toggle the ``fill`` attribute.\n\n\n## Bug tracker integration\n\nThe list of known issues for each check can be obtained from the configured bug tracker (see configuration section to disable).\n\nThe default implementation is for Bugzilla, and retrieves the bugs which have a certain string in their ``whiteboard`` field.\nFor example, if the ``SERVICE_NAME`` is ``delivery-checks`` and ``ENV_NAME`` is ``prod``, the bugs for the check ``server/heartbeat`` should have ``delivery-checks prod server/heartbeat`` in their ``whiteboard`` field to be listed.\n\nIf the bugs are only readable by authenticated users, then set ``BUGTRACKER_API_KEY`` to retrieve them all.\nNote that for security bugs only bug IDs are shown, summaries will be empty.\n\n\n## CLI\n\nUsing Docker, and a local config file:\n\n```\ndocker run -v `pwd`/config.toml:/app/config.toml mozilla/telescope check\n\ndocker run -v `pwd`/config.toml:/app/config.toml mozilla/telescope check myproject\n\ndocker run -v `pwd`/config.toml:/app/config.toml mozilla/telescope check myproject mycheck\n```\n\nOr from source (*requires Python 3.8+ and Poetry*):\n\n```\nmake check\n\nmake check project=myproject\n\nmake check project=myproject check=mycheck\n```\n\nReturn codes:\n\n- `0`: all checks were successful\n- `1`: some check failed\n- `2`: some check crashed (ie. Python exception)\n\n\n## Tests\n\n```\nmake tests\n```\n\nOr run `pytest` through `poetry` to pass arguments:\n\n```\npoetry run pytest -s -k log\n```\n\n## License\n\n*Telescope* is licensed under the MPLv2. See the `LICENSE` file for details.\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmozilla-services%2Ftelescope","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmozilla-services%2Ftelescope","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmozilla-services%2Ftelescope/lists"}