Microservices Payload Design

Originally published on my old blog on 30 March 2015. Lightly edited; notes added in 2026 are marked.

There are a lot of people talking about microservices at present. I understand it is fashionable, and a lot of people are trying to get rich consulting in the domain, but a lot of what I hear is just plain wrong or bad practice.

People are throwing microservices out there with little consideration for any of the basic requirements of operations: no idea how they will monitor them, no concept of how they will debug them, and no regard for how they will upgrade them.

I came from a dev background and over time migrated into operations. I dislike fragile, hard-to-debug components.

I have learnt the hard way just how difficult a distributed microservice architecture can be – but it is still (when designed correctly) a better choice than a hulking monolith of code.

I like my payloads to be debuggable. For this reason I like JSON as an interchange format. It isn't the most efficient representation, but it is easily read by humans and supported by most languages.

I like to know how long a request has taken through the system, so I add a UUID and a microsecond timestamp when each request is first seen. I also like to know how long each step takes, so I append a timestamp and an additional ID for every process the request passes through.

Doing this in a uniform way means you can take a payload from anywhere in the system and use the same tools to perform basic analysis on it.

It bloats the payload a little, but being able to see at a glance how quickly each worker is dealing with requests, how long each request takes end to end, and where the bottlenecks are lets you define and keep contracts with your service consumers, detect potential failures before they happen, and automatically trip circuit breakers to mitigate some of them.

I don't have all the answers, but this is starting to work well for me.

2026 note: This is distributed tracing, done by hand, a few years before it had a standard. W3C Trace Context (the traceparent header) and OpenTelemetry now give you the request ID, the per-hop spans and the timings without you inventing a payload format. Carrying a small hop list in the message itself is still worth doing on a message bus, where a trace can stop at the broker and the payload is often all you have. More in the observability patterns guide.