troubleshooting-astro-deployments

Name: troubleshooting-astro-deployments
Author: astronomer

436installs55forks

How to install troubleshooting-astro-deployments?

astronomer/agents/troubleshooting-astro-deployments

$npx -y skills add astronomer/agents --skill troubleshooting-astro-deployments

Installs into the current project.

Summary

Troubleshoot Astronomer production deployments with Astro CLI. Use when investigating deployment issues, viewing production logs, analyzing failures, or managing deployment environment variables.

Files · 1

View on GitHub

SKILL.md

1	# Astro Deployment Troubleshooting
2
3	This skill helps you diagnose and troubleshoot production Astronomer deployments using the Astro CLI.
4
5	> For deployment management, see the managing-astro-deployments skill.
6	> For local development, see the managing-astro-local-env skill.
7
8	---
9
10	## Quick Health Check
11
12	Start with these commands to get an overview:
13
14	```bash
15	# 1. List deployments to find target
16	astro deployment list
17
18	# 2. Get deployment overview
19	astro deployment inspect <DEPLOYMENT_ID>
20
21	# 3. Check for errors
22	astro deployment logs <DEPLOYMENT_ID> --error -c 50
23	```
24
25	---
26
27	## Viewing Deployment Logs
28
29	Use `-c` to control log count (default: 500). Log flags cannot be combined — use one component or level flag per command.
30
31	### Component-Specific Logs
32
33	View logs from specific Airflow components:
34
35	```bash
36	# Scheduler logs (DAG processing, task scheduling)
37	astro deployment logs <DEPLOYMENT_ID> --scheduler -c 50
38
39	# Worker logs (task execution)
40	astro deployment logs <DEPLOYMENT_ID> --workers -c 30
41
42	# Webserver logs (UI access, health checks)
43	astro deployment logs <DEPLOYMENT_ID> --webserver -c 30
44
45	# Triggerer logs (deferrable operators)
46	astro deployment logs <DEPLOYMENT_ID> --triggerer -c 30
47	```
48
49	### Log Level Filtering
50
51	Filter by severity:
52
53	```bash
54	# Error logs only (most useful for troubleshooting)
55	astro deployment logs <DEPLOYMENT_ID> --error -c 30
56
57	# Warning logs
58	astro deployment logs <DEPLOYMENT_ID> --warn -c 50
59
60	# Info-level logs
61	astro deployment logs <DEPLOYMENT_ID> --info -c 50
62	```
63
64	### Search Logs
65
66	Search for specific keywords:
67
68	```bash
69	# Search for specific error
70	astro deployment logs <DEPLOYMENT_ID> --keyword "ConnectionError"
71
72	# Search for specific DAG
73	astro deployment logs <DEPLOYMENT_ID> --keyword "my_dag_name" -c 100
74
75	# Find import errors
76	astro deployment logs <DEPLOYMENT_ID> --error --keyword "ImportError"
77
78	# Find task failures
79	astro deployment logs <DEPLOYMENT_ID> --error --keyword "Task failed"
80	```
81
82	---
83
84	## Complete Investigation Workflow
85
86	### Step 1: Identify the Problem
87
88	```bash
89	# List deployments with status
90	astro deployment list
91
92	# Get deployment details
93	astro deployment inspect <DEPLOYMENT_ID>
94	```
95
96	Look for:
97	- Status: HEALTHY vs UNHEALTHY
98	- Runtime version compatibility
99	- Resource limits (CPU, memory)
100	- Recent deployment timestamp
101
102	### Step 2: Check Error Logs
103
104	```bash
105	# Start with errors
106	astro deployment logs <DEPLOYMENT_ID> --error -c 50
107	```
108
109	Look for:
110	- Recurring error patterns
111	- Specific DAGs failing repeatedly
112	- Import errors or syntax errors
113	- Connection or credential errors
114
115	### Step 3: Review Scheduler Logs
116
117	```bash
118	# Check DAG processing
119	astro deployment logs <DEPLOYMENT_ID> --scheduler -c 30
120	```
121
122	Look for:
123	- DAG parse errors
124	- Scheduling delays
125	- Task queueing issues
126
127	### Step 4: Check Worker Logs
128
129	```bash
130	# Check task execution
131	astro deployment logs <DEPLOYMENT_ID> --workers -c 30
132	```
133
134	Look for:
135	- Task execution failures
136	- Resource exhaustion
137	- Timeout errors
138
139	### Step 5: Verify Configuration
140
141	```bash
142	# Check environment variables
143	astro deployment variable list --deployment-id <DEPLOYMENT_ID>
144
145	# Verify deployment settings
146	astro deployment inspect <DEPLOYMENT_ID>
147	```
148
149	Look for:
150	- Missing or incorrect environment variables
151	- Secrets configuration (AIRFLOW__SECRETS__BACKEND)
152	- Connection configuration
153
154	---
155
156	## Common Investigation Patterns
157
158	### Recurring DAG Failures
159
160	Follow the complete investigation workflow above, then narrow to the specific DAG:
161
162	```bash
163	astro deployment logs <DEPLOYMENT_ID> --keyword "my_dag_name" -c 100
164	```
165
166	### Resource Issues
167
168	```bash
169	# 1. Check deployment resource allocation
170	astro deployment inspect <DEPLOYMENT_ID>
171	# Look for: resource_quota_cpu, resource_quota_memory
172	# Worker queue: max_worker_count, worker_type
173
174	# 2. Check for worker scaling issues
175	astro deployment logs <DEPLOYMENT_ID> --workers -c 50
176
177	# 3. Look for out-of-memory errors
178	astro deployment logs <DEPLOYMENT_ID> --error --keyword "memory"
179	```
180
181	### Configuration Problems
182
183	```bash
184	# 1. Review environment variables
185	astro deployment variable list --deployment-id <DEPLOYMENT_ID>
186
187	# 2. Check for secrets backend configuration
188	# Look for: AIRFLOW__SECRETS__BACKEND, AIRFLOW__SECRETS__BACKEND_KWARGS
189
190	# 3. Verify deployment settings
191	astro deployment inspect <DEPLOYMENT_ID>
192
193	# 4. Check webserver logs for auth issues
194	astro deployment logs <DEPLOYMENT_ID> --webserver -c 30
195	```
196
197	### Import Errors
198
199	```bash
200	# 1. Find import errors
201	astro deployment logs <DEPLOYMENT_ID> --error --keyword "ImportError"
202
203	# 2. Check scheduler for parse failures
204	astro deployment logs <DEPLOYMENT_ID> --scheduler --keyword "Failed to import" -c 50
205
206	# 3. Verify dependencies were deployed
207	astro deployment inspect <DEPLOYMENT_ID>
208	# Check: current_tag, last deployment timestam

People who liked this also viewed

6 picks

Type

troubleshooting-astro-deployments

436installs55forks

View on GitHub

How to install troubleshooting-astro-deployments?

astronomer/agents/troubleshooting-astro-deployments

$npx -y skills add astronomer/agents --skill troubleshooting-astro-deployments

Installs into the current project.

Summary

Troubleshoot Astronomer production deployments with Astro CLI. Use when investigating deployment issues, viewing production logs, analyzing failures, or managing deployment environment variables.

Files · 1

View on GitHub

SKILL.md

1	# Astro Deployment Troubleshooting
2
3	This skill helps you diagnose and troubleshoot production Astronomer deployments using the Astro CLI.
4
5	> For deployment management, see the managing-astro-deployments skill.
6	> For local development, see the managing-astro-local-env skill.
7
8	---
9
10	## Quick Health Check
11
12	Start with these commands to get an overview:
13
14	```bash
15	# 1. List deployments to find target
16	astro deployment list
17
18	# 2. Get deployment overview
19	astro deployment inspect <DEPLOYMENT_ID>
20
21	# 3. Check for errors
22	astro deployment logs <DEPLOYMENT_ID> --error -c 50
23	```
24
25	---
26
27	## Viewing Deployment Logs
28
29	Use `-c` to control log count (default: 500). Log flags cannot be combined — use one component or level flag per command.
30
31	### Component-Specific Logs
32
33	View logs from specific Airflow components:
34
35	```bash
36	# Scheduler logs (DAG processing, task scheduling)
37	astro deployment logs <DEPLOYMENT_ID> --scheduler -c 50
38
39	# Worker logs (task execution)
40	astro deployment logs <DEPLOYMENT_ID> --workers -c 30
41
42	# Webserver logs (UI access, health checks)
43	astro deployment logs <DEPLOYMENT_ID> --webserver -c 30
44
45	# Triggerer logs (deferrable operators)
46	astro deployment logs <DEPLOYMENT_ID> --triggerer -c 30
47	```
48
49	### Log Level Filtering
50
51	Filter by severity:
52
53	```bash
54	# Error logs only (most useful for troubleshooting)
55	astro deployment logs <DEPLOYMENT_ID> --error -c 30
56
57	# Warning logs
58	astro deployment logs <DEPLOYMENT_ID> --warn -c 50
59
60	# Info-level logs
61	astro deployment logs <DEPLOYMENT_ID> --info -c 50
62	```
63
64	### Search Logs
65
66	Search for specific keywords:
67
68	```bash
69	# Search for specific error
70	astro deployment logs <DEPLOYMENT_ID> --keyword "ConnectionError"
71
72	# Search for specific DAG
73	astro deployment logs <DEPLOYMENT_ID> --keyword "my_dag_name" -c 100
74
75	# Find import errors
76	astro deployment logs <DEPLOYMENT_ID> --error --keyword "ImportError"
77
78	# Find task failures
79	astro deployment logs <DEPLOYMENT_ID> --error --keyword "Task failed"
80	```
81
82	---
83
84	## Complete Investigation Workflow
85
86	### Step 1: Identify the Problem
87
88	```bash
89	# List deployments with status
90	astro deployment list
91
92	# Get deployment details
93	astro deployment inspect <DEPLOYMENT_ID>
94	```
95
96	Look for:
97	- Status: HEALTHY vs UNHEALTHY
98	- Runtime version compatibility
99	- Resource limits (CPU, memory)
100	- Recent deployment timestamp
101
102	### Step 2: Check Error Logs
103
104	```bash
105	# Start with errors
106	astro deployment logs <DEPLOYMENT_ID> --error -c 50
107	```
108
109	Look for:
110	- Recurring error patterns
111	- Specific DAGs failing repeatedly
112	- Import errors or syntax errors
113	- Connection or credential errors
114
115	### Step 3: Review Scheduler Logs
116
117	```bash
118	# Check DAG processing
119	astro deployment logs <DEPLOYMENT_ID> --scheduler -c 30
120	```
121
122	Look for:
123	- DAG parse errors
124	- Scheduling delays
125	- Task queueing issues
126
127	### Step 4: Check Worker Logs
128
129	```bash
130	# Check task execution
131	astro deployment logs <DEPLOYMENT_ID> --workers -c 30
132	```
133
134	Look for:
135	- Task execution failures
136	- Resource exhaustion
137	- Timeout errors
138
139	### Step 5: Verify Configuration
140
141	```bash
142	# Check environment variables
143	astro deployment variable list --deployment-id <DEPLOYMENT_ID>
144
145	# Verify deployment settings
146	astro deployment inspect <DEPLOYMENT_ID>
147	```
148
149	Look for:
150	- Missing or incorrect environment variables
151	- Secrets configuration (AIRFLOW__SECRETS__BACKEND)
152	- Connection configuration
153
154	---
155
156	## Common Investigation Patterns
157
158	### Recurring DAG Failures
159
160	Follow the complete investigation workflow above, then narrow to the specific DAG:
161
162	```bash
163	astro deployment logs <DEPLOYMENT_ID> --keyword "my_dag_name" -c 100
164	```
165
166	### Resource Issues
167
168	```bash
169	# 1. Check deployment resource allocation
170	astro deployment inspect <DEPLOYMENT_ID>
171	# Look for: resource_quota_cpu, resource_quota_memory
172	# Worker queue: max_worker_count, worker_type
173
174	# 2. Check for worker scaling issues
175	astro deployment logs <DEPLOYMENT_ID> --workers -c 50
176
177	# 3. Look for out-of-memory errors
178	astro deployment logs <DEPLOYMENT_ID> --error --keyword "memory"
179	```
180
181	### Configuration Problems
182
183	```bash
184	# 1. Review environment variables
185	astro deployment variable list --deployment-id <DEPLOYMENT_ID>
186
187	# 2. Check for secrets backend configuration
188	# Look for: AIRFLOW__SECRETS__BACKEND, AIRFLOW__SECRETS__BACKEND_KWARGS
189
190	# 3. Verify deployment settings
191	astro deployment inspect <DEPLOYMENT_ID>
192
193	# 4. Check webserver logs for auth issues
194	astro deployment logs <DEPLOYMENT_ID> --webserver -c 30
195	```
196
197	### Import Errors
198
199	```bash
200	# 1. Find import errors
201	astro deployment logs <DEPLOYMENT_ID> --error --keyword "ImportError"
202
203	# 2. Check scheduler for parse failures
204	astro deployment logs <DEPLOYMENT_ID> --scheduler --keyword "Failed to import" -c 50
205
206	# 3. Verify dependencies were deployed
207	astro deployment inspect <DEPLOYMENT_ID>
208	# Check: current_tag, last deployment timestam

People who liked this also viewed

6 picks

Type