Add Observability page to docs #9723
Conversation
|
+1 for the idea, and thanks for the content. My one note would be that it's a bit early to mention django-prometheus as the first example tool on that page. The package has just been migrated to django-commons, and it still requires a not-so-small amount of work to reach a properly functioning state. |
Fair point. As a first measure I've moved it below the OpenTelemetry section. Do you think we should add a note about the current state of django-prometheus, or remove it entirely? Given that Prometheus is generally a go-to solution for metrics, and there doesn't seem to be a better alternative for Django, my vote would be to leave it in. |
There was a problem hiding this comment.
Great content, thanks for taking the time to put this together, however I don't see a lot of it being DRF specific: it's 90% applicable to any Django projects (except maybe Apitally). Why should this be in the DRF docs?
Sorry for the pushback, but I'm generally -1 on this.
| ### Apitally | ||
|
|
||
| [Apitally](https://apitally.io/) is a simple API monitoring, analytics, and request logging tool with an integration for Django REST framework. It provides intuitive dashboards with metrics and insights into API requests, errors, performance and consumers. | ||
|
|
||
| The [apitally](https://pypi.org/project/apitally/) package integrates with Django applications through middleware, which automatically captures metrics for API requests and responses, and synchronizes with Apitally in the background. See DRF-specific setup guide [here](https://docs.apitally.io/frameworks/django-rest-framework). |
There was a problem hiding this comment.
I appreciate that this is your baby 😃 but I'm a bit reluctant to place some paid services into our docs. If we start to add this one, why not add others as well? Where do we draw the line and stop adding? I don't really fancy maintaining an awsome-observability list as part of the docs.
There was a problem hiding this comment.
I completely understand the concern. That said, I'd argue that Apitally is highly relevant in this context, offers DRF-specific integration and docs, and aligns closely with the needs of the audience likely to visit this page. It's a paid service, but very affordable – similar to Sentry.
I completely understand the need to draw a line in terms of linking paid services though, especially as that's a benefit offered to organizations that sponsor DRF. To help with that, I'll sign Apitally up to a corporate funding plan for DRF. That way, inclusion can be based on clear criteria:
- Direct relevance to the topic
- DRF-specific integration/support
- Active sponsorship of DRF
docs/topics/observability.md
Outdated
| ### django-health-check | ||
|
|
||
| [django-health-check](https://pypi.org/project/django-health-check/) provides a set of health check endpoints for Django applications. It allows you to monitor the status of various application components including database connections, cache backends, and custom services. | ||
|
|
||
| The library is helpful for production deployments as it enables load balancers, orchestration systems, and monitoring tools to determine application health. It supports both simple health checks and detailed status reporting for different application components. | ||
|
|
||
| ### django-silk | ||
|
|
||
| [django-silk](https://pypi.org/project/django-silk/) is a profiling tool designed specifically for Django applications. It provides detailed insights into request performance, database queries, and custom code blocks or functions through context managers and decorators. | ||
|
|
||
| The package offers a web-based interface for analyzing requests, database queries, and profiling code. It's primarily intended for local development to identify performance bottlenecks before they reach production. |
There was a problem hiding this comment.
These 2 are not specific to DRF
There was a problem hiding this comment.
I've removed django-silk as it's indeed not particularly specific to APIs / DRF and also not meant for production use.
I do think we should keep django-health-check in here though. While it's not DRF-specific, it's highly relevant for APIs. Most production APIs need health check endpoints and this package seems to be widely used for that purpose.
|
|
||
| The package offers a web-based interface for analyzing requests, database queries, and profiling code. It's primarily intended for local development to identify performance bottlenecks before they reach production. | ||
|
|
||
| ### Sentry |
There was a problem hiding this comment.
They're sponsoring us (I think), so that might be a good enough criteria to add them here. While you can self-host, it's also primarily a paid (albeit relatively cheap) service
Thanks for your review! I get where you’re coming from. Some of what’s covered here does also apply to Django more broadly. But I’d suggest looking at it less in terms of "is this DRF-specific?" and more in terms of "is this relevant and useful to DRF users?" My goal was to help developers using DRF understand how to approach observability in their projects. Even if the techniques and tools apply beyond DRF, the framing and examples are written with DRF users in mind, and the content meets a real need for guidance in this area (imo) – something the current docs don’t cover. |
Description
Adds a new page about Observability to the documentation under Topics.
Happy to evolve this further. Feedback is very welcome!