From b107621e5e9f00887bba296dff182f8e7931fd9e Mon Sep 17 00:00:00 2001 From: sund02 Date: Tue, 29 Sep 2026 20:57:56 +0200 Subject: [PATCH 1/3] Add tutorial proposal: Diagnosing HTTP Service Errors with Prometheus and PromQL --- .../jafarm-elenapan/README.md | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 contributions/executable-tutorial/jafarm-elenapan/README.md diff --git a/contributions/executable-tutorial/jafarm-elenapan/README.md b/contributions/executable-tutorial/jafarm-elenapan/README.md new file mode 100644 index 0000000000..b0aa580fc3 --- /dev/null +++ b/contributions/executable-tutorial/jafarm-elenapan/README.md @@ -0,0 +1,47 @@ +# Assignment Proposal + +## Title + +Diagnosing HTTP Service Errors with Prometheus and PromQL + +## Names and KTH ID + + - Jafar (jafarm@kth.se) + - Elena Pan (elenapan@kth.se) + +## Deadline + +- Task 3 + +## Category + +- Executable tutorial + +## Description + +This tutorial teaches how to investigate an operational failure in a running HTTP service using application metrics and PromQL. We observe healthy traffic, introduce a controlled failure, diagnose the affected endpoint, and verify recovery using Prometheus. + +By the end of the tutorial, we will be able to: explain how an instrumented application exposes metrics and how Prometheus collects them; distinguish cumulative counters from request rates; write PromQL queries for request rate and error ratio grouped by endpoint; use metric labels to locate a failing endpoint and confirm recovery; and explain the limitations of metrics-based diagnosis. + +The tutorial is a guided, ~20-30 minute Killercoda scenario. Automated setup starts a small instrumented Python application, a traffic generator, and Prometheus inside the browser. Only a free Killercoda account is needed: no local install, paid services, or external credentials. Each step includes executable commands, expected results, and an explanation of what it does and why. + +Workflow: + +1. Start the environment and verify Prometheus is scraping the application's metrics. +2. Generate continuous traffic against two endpoints and query request counters and rates. +3. Enable a failure mode that makes one endpoint return HTTP 500s while metrics stay available. +4. Compute the overall error ratio, then group by endpoint to find where failures occur, showing how aggregation can hide per-endpoint issues. +5. Disable the failure, keep generating traffic, and watch the error ratio recover as the query window moves past the incident. +6. Reflect on useful applications, design choices, and limitations of the approach. + +**System architecture.** A traffic-generation script sends requests to a small HTTP application, which exposes a request counter via `/metrics`, labeled by endpoint and status code. Prometheus scrapes these metrics on an interval and serves them for querying and graphing. A diagram will show the application, traffic flow, and metrics collection path. + +**Design decisions.** Prometheus combines metrics collection and querying in one tool, keeping the exercise focused. Counters support rate and error-ratio calculations, while endpoint/status labels support diagnosis; labels use a bounded set of values to avoid time-series growth. A provided container setup and scripted traffic/failure controls make the environment and the incident fully reproducible. + +**Reflection on applicability.** This approach is useful for spotting service-wide or endpoint-specific spikes in errors, but aggregate metrics can hide individual failures, error ratios can mislead under low traffic, and scrape/query windows introduce observation delay. Metrics locate symptoms; logs or traces are often still needed to find the root cause. This makes the tutorial's relevance clearest for developers and operators responsible for keeping a running service healthy. + +The tutorial will be validated end-to-end from a fresh Killercoda environment (setup, healthy traffic, failure injection, diagnosis, and recovery) within Killercoda's one-hour free session limit, before submission. + +**Relevance** + +This tutorial addresses monitoring and observability by showing how runtime measurements support incident investigation and recovery. It connects application instrumentation, automated metrics collection, and operational diagnosis in a single reproducible workflow, and is scoped narrowly around interpreting runtime metrics for service health rather than overlapping with other DevOps aspects such as testing/CI or deployment pipelines. From 85bf2cdddaeb7e0e970e6c528ac6e28d0e8a30a3 Mon Sep 17 00:00:00 2001 From: sund02 Date: Mon, 5 Oct 2026 11:31:52 +0200 Subject: [PATCH 2/3] Add submission links for tutorial artifact --- contributions/executable-tutorial/jafarm-elenapan/README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/contributions/executable-tutorial/jafarm-elenapan/README.md b/contributions/executable-tutorial/jafarm-elenapan/README.md index b0aa580fc3..bab6494dd3 100644 --- a/contributions/executable-tutorial/jafarm-elenapan/README.md +++ b/contributions/executable-tutorial/jafarm-elenapan/README.md @@ -45,3 +45,8 @@ The tutorial will be validated end-to-end from a fresh Killercoda environment (s **Relevance** This tutorial addresses monitoring and observability by showing how runtime measurements support incident investigation and recovery. It connects application instrumentation, automated metrics collection, and operational diagnosis in a single reproducible workflow, and is scoped narrowly around interpreting runtime metrics for service health rather than overlapping with other DevOps aspects such as testing/CI or deployment pipelines. + +## Submission + +- Killercoda scenario: https://killercoda.com/sund02/course/killercoda +- Source repository: https://github.com/sund02/promql-http-error-diagnosis From 586390b62437626fa94381707f4bf68b0fb22f63 Mon Sep 17 00:00:00 2001 From: sund02 Date: Mon, 5 Oct 2026 11:47:13 +0200 Subject: [PATCH 3/3] Move submission links into Description, drop extra heading --- .../executable-tutorial/jafarm-elenapan/README.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/contributions/executable-tutorial/jafarm-elenapan/README.md b/contributions/executable-tutorial/jafarm-elenapan/README.md index bab6494dd3..0e62ae2e30 100644 --- a/contributions/executable-tutorial/jafarm-elenapan/README.md +++ b/contributions/executable-tutorial/jafarm-elenapan/README.md @@ -19,6 +19,8 @@ Diagnosing HTTP Service Errors with Prometheus and PromQL ## Description +**Tutorial:** [Killercoda](https://killercoda.com/sund02/course/killercoda) — **Source:** [GitHub](https://github.com/sund02/promql-http-error-diagnosis) + This tutorial teaches how to investigate an operational failure in a running HTTP service using application metrics and PromQL. We observe healthy traffic, introduce a controlled failure, diagnose the affected endpoint, and verify recovery using Prometheus. By the end of the tutorial, we will be able to: explain how an instrumented application exposes metrics and how Prometheus collects them; distinguish cumulative counters from request rates; write PromQL queries for request rate and error ratio grouped by endpoint; use metric labels to locate a failing endpoint and confirm recovery; and explain the limitations of metrics-based diagnosis. @@ -45,8 +47,3 @@ The tutorial will be validated end-to-end from a fresh Killercoda environment (s **Relevance** This tutorial addresses monitoring and observability by showing how runtime measurements support incident investigation and recovery. It connects application instrumentation, automated metrics collection, and operational diagnosis in a single reproducible workflow, and is scoped narrowly around interpreting runtime metrics for service health rather than overlapping with other DevOps aspects such as testing/CI or deployment pipelines. - -## Submission - -- Killercoda scenario: https://killercoda.com/sund02/course/killercoda -- Source repository: https://github.com/sund02/promql-http-error-diagnosis