search

guardrail-dev / guardrail

Principled code generation from OpenAPI specifications
https://guardrail.dev
MIT License
526 stars 133 forks source link

Document an example of tracing end-to-end #271

Open kubum opened 5 years ago

kubum commented 5 years ago

The tracing capability looks very good and promising. I wonder if you have a snippet how would you recommend to integrate it with Zipkin or OpenTracing?

Also, the TraceBuilder type signature is TraceBuilder = String => HttpClient => HttpClient, which makes it more difficult to use it for tracing something that is not represented as HTTP, for instance, a database query. What would be the recommended way of doing it?

I am happy to contribute to the docs about tracing. So far the test case for full tracing was the main inspiration, but it would be great to find out how do people use it in production.

Thank you!

blast-hardcheese commented 5 years ago

I generalized TraceBuilder from something we use internally; the way TraceBuilder is right now is intended to provide building blocks for threading through only the most minimal of information through clients (populating headers that will be picked up by downstream).

Depending on how you use OpenTracing or Zipkin, enhancing TraceBuilder to be a trait that supports lifecycle management operations (trace(label: String)(func: EitherT[F, Either[Throwable, HttpResponse], T]): EitherT[F, Either[Throwable, HttpResponse], T], propagate: HttpClient => HttpClient) and whatever else your underlying library needs to operate (markers during operation? "marshalling started/stopped", "http session started/stopped", "response decoding/finished"?)

These are just some ideas, offering the basics of what we're using offers. Are you interested and available to spitball what you think a minimal example of the generated code would look like?

blast-hardcheese commented 5 years ago

In hindsight, I wish I'd just implemented the trait upfront, I think it would have painted a much clearer picture for those trying to follow along.

kubum commented 5 years ago

Thank you for the quick reply! I see, I agree with you, it fits well for inter-http-services communication. I can try to concoct an example based on it.

I am more leaning towards idea in HTTP4s Tracer [1], the way TracerLog work. So far, unfortunately, the services aren't using http4s yet. What do you think about it?

[1] https://gvolpe.github.io/http4s-tracer/guide.html#tracers

blast-hardcheese commented 5 years ago

TracerLog sounds like part of a useful implementation!

Especially if the parameter can be expressed with a degree of compositionality, such that we get individual trace elements as well as distributed tracing propagation (a la OpenTracing), based on what functionality the consumer needs, we'd be in a really good place.