Report spans, span events and metrics to the Effect DevTools, or serve the DevTools side yourself.
pyfect.devtools speaks the protocol of the Effect DevTools (the VS Code extension and its
server), so a pyfect program shows up there as an Effect program does. Each line on the wire
is one JSON message, the same in both directions as Effect's, so a pyfect app can report to
Effect's DevTools server and an Effect app to a pyfect one.
Reporting to the DevTools#
devtools.layer() reports every span of the program it's provided to the DevTools at
ws://localhost:34437, the extension's default; devtools.layer(url) reports to another
address. It opens the WebSocket with the websockets library, so install the
pyfect-dev[websockets] extra. Two other layers take the connection from you:
devtools.layer_web_socket(url) opens it with the WebSocketConstructor you provide, and
devtools.layer_socket reports over the Socket you provide, such as a TCP one from
socket.layer_net(port, host).
The protocol carries:
- Spans, sent when they start and again when they end, with their parent, attributes and status. An attribute added while the span runs appears in the end message.
- Span events: each log inside a span is an event of that span.
- Metrics: a
MetricsSnapshotof every metric, each time the DevTools asks with aMetricsRequest, and a last one when the layer is released.
The protocol has no fibers, in pyfect as in Effect, so the DevTools shows none.
Serving the DevTools side#
devtools.server.run(handle) is the other end: for each app that connects to the
SocketServer, it calls handle with a Client. client.queue has the app's spans, span
events and snapshots (pings are answered for it), and client.send(request) sends it a
MetricsRequest. The default client speaks WebSocket, so serve on
socket.server.layer_web_socket(port=..., host=...); socket.server.layer(port, host) is a
TCP server, for apps reporting with devtools.layer_socket.
from typing import Any
import pyfect as fx
from pyfect import devtools, logger
from pyfect.devtools import server as devtools_server
from pyfect.net.net_address import InetAddressV4
from pyfect.queue import Queue
from pyfect.socket import server as socket_server
@fx.fn("checkout")
def checkout(order: int):
yield from fx.annotate_current_span("order", order)
yield from fx.log_info("charging")
yield from fx.void.with_span("charge")
def describe(request: devtools_server.RequestWithoutPing) -> str:
match request["_tag"]:
case "Span":
return f"Span {request['name']}: {request['status']['_tag']}"
case "SpanEvent":
return f"SpanEvent {request['name']}"
case "MetricsSnapshot":
return "MetricsSnapshot"
@fx.fn
def program():
# The DevTools side: a WebSocket SocketServer, the protocol the default client speaks.
srv = yield from socket_server.SocketServer()
assert isinstance(srv.address, InetAddressV4)
seen = yield from Queue[str, Any].unbounded()
def handle(client: devtools_server.Client) -> fx.Effect[Any]:
return client.queue.take().flat_map(lambda r: seen.offer(describe(r))).forever()
yield from devtools_server.run(handle).fork_scoped()
# The app side: with devtools.layer(url), every span is reported to the DevTools.
@fx.fn
def app():
yield from checkout(7)
while (line := (yield from seen.take().timeout("5 seconds"))) != "Span checkout: Ended":
if line != "MetricsSnapshot":
print(line)
print(line)
url = f"ws://127.0.0.1:{srv.address.port}"
yield from app().pipe(fx.provide(devtools.layer(url)))
server = socket_server.layer_web_socket(port=0, host="127.0.0.1")
# Logs go only to their span's events here, so the DevTools gets them and the console does not.
quiet = logger.layer([logger.tracer_logger])
fx.run_main(fx.scoped(program()).pipe(fx.provide(server)).pipe(fx.provide(quiet)))When an app disconnects, its queue shuts down: requests its handler has not taken yet are
dropped, and a handler waiting on client.queue.take() is interrupted, which the server logs
as "Unhandled error in SocketServer". Effect's server does the same. The snippet takes the
app's messages while it is still connected for that reason.
Reference: pyfect.devtools,
pyfect.devtools.server,
pyfect.socket.server.