Added ASGI application

[Skeen]

This PR introduces an ASGI counterpart to the current WSGI app.

The ASGI code itself is moved into a seperate module asgi.py, which is conditionally included as it is only valid in Python 3 (due to async/await calls).

[brian-brazil]

I'd prefer not to have to maintain yet another copy of the exposition http handling for a subtly difference interface. Is there not some interface all of these can share?

[Skeen]

I understand your hesitance to adapt yet another interface. The README file is already quite crowded.

As for whether there is a common interface all of these can share, I wanna say yes, there is the PEP-3333 standard WSGI and it's spiritual successor ASGI.

• Supporting just these two should be enough, as any web-framework should be able to integrate with one or the other, depending on whether it's a synchronous or asynchronous framework.

My last though is that WSGI and ASGI should not be considered equal to the frameworks. As they are gateway interfaces and thus more general than specific frameworks.

[Skeen]

Note: I have closed the PR for the Quart extension of the README file, I included it solely for completeness to have a flask-equivalent ASGI framework example.

[brian-brazil]

It doesn't matter to me why this exists, it matters that we're already duplicating this code 3 times for various things that were popular at various times.

[Skeen]

How would you feel about cleaning up, by deprecating the twisted code, removing the flask and python http documentation and going solely with the code+examples for the gateway interfaces?

The gateway interfaces produces production quality endpoints in standard defined ways, and the integrations are simple in most languages, either via routers, middleware or adapters.

For Flask/Django it's common practice to utilize WSGI middlewares, for Quart/Django it's common practice to utliize ASGI middleware. Twisted has a WSGIResource which can call any WSGI app, thus I don't see the need for the MetricsResource for twisted.

[brian-brazil]

Is it possible to get twisted to use one of the *sgi apis? That way it could be replaced by docs.

[Skeen]

Yea, that is very much possible.

To use the make_wsgi_app as a twisted resource, simply replace MetricsResource(), with: WSGIResource(reactor, reactor.getThreadPool(), make_wsgi_app()).
Or use txasgiresource to do the same thing with the make_asgi_app, by replacing MetricsResource() with ASGIResource(make_asgi_app()).

The example in the README becomes:

from prometheus_client import make_wsgi_app
from twisted.web.wsgi import WSGIResource
from twisted.web.server import Site
from twisted.web.resource import Resource
from twisted.internet import reactor

root = Resource()
root.putChild(b'metrics', WSGIResource(reactor, reactor.getThreadPool(), make_wsgi_app()))

factory = Site(root)
reactor.listenTCP(8000, factory)
reactor.run()

Using WSGI, and:

from prometheus_client import make_asgi_app
from txasgiresource import ASGIResource
from twisted.web.server import Site
from twisted.web.resource import Resource
from twisted.internet import reactor
from functools import partial

root = Resource()
root.putChild(b'metrics', ASGIResource(lambda scope: partial(make_asgi_app(), scope)))

factory = Site(root)
reactor.listenTCP(8000, factory)
reactor.run()

Using ASGI and txasgiresource.

Either way all the framework specific code for twisted can be deprecated/removed.

Potentially an alias can be setup, such as:

from twisted.web.wsgi import WSGIResource
from twisted.internet import reactor
from . import exposition, REGISTRY
MetricsResource = lambda registry=REGISTRY: WSGIResource(reactor, reactor.getThreadPool(), exposition.make_wsgi_app(registry))

To maintain backwards compatability.

[brian-brazil]

If we can do that then and avoid duplicating the parameter handing code, that sounds good.

[Skeen]

I will do it when I can get around to it.

How do you feel about the MetricsHandler, and start_http_server + _ThreadingSimpleServer?

We could eliminate _ThreadingSimpleServer by making start_http_server an alias of start_wsgi_server. If we did that we could additionally deprecate MetricsHandler, and potentially rewrite it to wrap and call the WSGI app from make_wsgi_app? - How do you feel about it this?

[brian-brazil]

MetricsHandler is used by users, so it should continue to work. I'm okay with switching around how start_http_server works as long as it can still handle concurrent scrapes.

[Skeen]

What do you think about this?

[brian-brazil]

Thanks!

[pquentin]

@Skeen Thanks for this! It works really well, and I was able to add it to a FastAPI app like this:

from fastapi import FastAPI
import prometheus_client

app = FastAPI()
metrics_app = prometheus_client.make_asgi_app()
app.mount("/metrics", metrics_app)

@brian-brazil Can you please consider releasing a new version to PyPI? Thanks!

[denisSurkov]

Hi!

ASGI is really cool feature. Especially for fastapi app (see comment above). When are you going to release asgi version to PyPI?

[whg517]

I can't wait to use Prometheus in fastapi. But I noticed that prometheus_client has not released a new version. So I chose to starlette_exporter. At least for now, there are no functional issues. You can try it, too.
@denisSurkov @pquentin

[pquentin]

@brian-brazil Thank you for the release! 🎉

[aLowMagic]

@Skeen Thanks for this! It works really well, and I was able to add it to a FastAPI app like this:

from fastapi import FastAPI
import prometheus_client

app = FastAPI()
metrics_app = prometheus_client.make_asgi_app()
app.mount("/metrics", metrics_app)

@brian-brazil Can you please consider releasing a new version to PyPI? Thanks!

could you please remain me that, how can i add a count metrics in the asgi mode? Thanks alot

[Skeen]

could you please remain me that, how can i add a count metrics in the asgi mode? Thanks alot

The same way you'd do it for non-asgi:

from prometheus_client import Counter
c = Counter('my_failures', 'Description of counter')
c.inc()     # Increment by 1
c.inc(1.6)  # Increment by given value

[aLowMagic]

could you please remain me that, how can i add a count metrics in the asgi mode? Thanks alot

The same way you'd do it for non-asgi:

from prometheus_client import Counter
c = Counter('my_failures', 'Description of counter')
c.inc()     # Increment by 1
c.inc(1.6)  # Increment by given value

Thanks a lot!

[aLowMagic]

could you please remain me that, how can i add a count metrics in the asgi mode? Thanks alot

The same way you'd do it for non-asgi:

from prometheus_client import Counter
c = Counter('my_failures', 'Description of counter')
c.inc()     # Increment by 1
c.inc(1.6)  # Increment by given value

Hello master, it's me again~
I found that, in the multiprocess mode, if two fastapi(asgi) workers exists, their are two counter exists, and the data will like:

and then i need calculate the qps like:

sum(increase(context_app_calls_total{app_name=~".*", endpoint="/test", instance="0.0.0.0:8000", job="8000_metrics", method="get", status_code="200"}[1m])/60)

will i get correct result like this way? Thanks a lot

[Skeen]

Hi @aLowMagic

I don't think this PR is the right place to ask for help like this, or to have these discussions, as it's unrelated to ASGI itself.
The challenge your facing is a more generic one of combining multiple parallel data-series, irrelevant to how the data series are collected, or which programming language is used to do that collection.

I would suggest you have a look at: https://prometheus.io/community/ - And seek help there :)

[aLowMagic]

Hi @aLowMagic

I don't think this PR is the right place to ask for help like this, or to have these discussions, as it's unrelated to ASGI itself.
The challenge your facing is a more generic one of combining multiple parallel data-series, irrelevant to how the data series are collected, or which programming language is used to do that collection.

I would suggest you have a look at: https://prometheus.io/community/ - And seek help there :)

Thanks a lot~