Telescope is a CLI developed by Astronomer for generating additional metrics from your Airflow environments. It connects directly to Airflow and generates snapshots of your usage and configurations at different times. This information can help Astronomer support diagnose and resolve issues in your environments.
Telescope assumes your current permissions whenever you run a command. If you have the correct permissions, Telescope can observe your Airflow environments for a specific period and then generate a report that you can share with Astronomer support.
Astronomer recommends that you observe your Deployments with Telescope at least once a month. When required to assist with troubleshooting, you can observe local projects running with the Astro CLI.
To observe a local project with Telescope, you need:
docker exec permissions.docker.sock.To observe Software Deployments on Kubernetes with Telescope, you need:
To observe a standalone Airflow environment with Telescope, you need:
Depending on where you want to run Telescope, install the CLI on a machine that has permissions for either Docker or your Software Kubernetes cluster.
Go to the Releases page of the Telescope GitHub repository. Based on the operating system and CPU architecture of your machine, download one of the .zip files for the latest available version of Telescope and make it an executable.
For example, to install Telescope on a Linux machine with x86_64 CPU architecture, you would run:
In your Kubernetes cluster, run the following command:
This command observes all scheduler containers in the cluster and outputs the results of the observation to a file named <observation-date>.<your-organization-name>.data.json.
By default, Telescope only observes Pods with the label component=scheduler. If your Deployments use an alternative label to denote scheduler Pods, use --label-selector in your command. For example, if your label for scheduler pods is role=scheduler, you would run.
Open your Astro project and run the following command:
This command observes scheduler containers on Docker and outputs the results of the observation to a file named <observation-date>.<your-organization-name>.data.json.
You can use Telescope to observe both Apache Airflow environments and standalone Astronomer Certified environments. This setup assumes you have two machines:
On the remote machine running Airflow, create a file named ~/.ssh/config and then open it.
Add the following configuration to the file:
Optional. Add additional configurations, such as an SSH key. See Using the SSH Config File.
Optional. Repeat steps 1 through 3 for any additional remote machines that you want to observe with Telescope.
On your local machine, create a file named hosts.yaml and open it.
Add the following configuration to the file:
Run the following command to observe Airflow on the remote machine:
This command observes the Airflow scheduler and outputs the results of the observation to a file named <observation-date>.<your-organization-name>.data.json.
After Telescope observes an Airflow environment, it generates a file ending in data.json with information about the environment. The report can include the following details:
Telescope never collects the DAG codes or the contents of Airflow configurations such as variables and connections. To hide DAG names, use the --dag-obfuscation flag in your Telescope command.
For all report details and functions, see the Telescope GitHub repository.
<Organization-name>: Telescope Resultsdata.json file that Telescope generated to the ticket.Telescope includes advanced settings for customizing your reports and observing Airflow environments running in containers with custom names. For more information about these settings, see Telescope README or run telescope --help.