├── LICENSE
├── README.md
└── checklist.md


/LICENSE:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2020 distributed-tracing-in-practice
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # instrumentation-checklist
2 | 
3 | This repository contains a markdown verison of the Instrumentation Checklist included in Chapter 4 of _Distributed Tracing in Practice_.


--------------------------------------------------------------------------------
/checklist.md:
--------------------------------------------------------------------------------
 1 | # Instrumentation Checklist
 2 | 
 3 | ## Span Status and Creation
 4 | * All error conditions under a given span appropriately set the span status to an error state.
 5 | * RPC framework result codes are mapped to span status (i.e., Internal Error, Not Found, etc.).
 6 | * All spans that are started are also finished, even in the case of unrecoverable errors if possible.
 7 | * Spans should only represent work that is semantically important to the request life cycle of a service; try not to create spans around endpoints only receiving synthetic traffic, like a /status or /health endpoint.
 8 | 
 9 | ## Span Boundaries
10 | * Egress and ingress spans have appropriate labels (SpanKind is set).
11 | * Egress and ingress spans have appropriate relationships (client/server, consumer/producer).
12 | * Internal spans are appropriately labeled and do not imply a remote call.
13 | 
14 | ## Attributes
15 | * Spans include a version attribute for the service they represent.
16 | * Spans that represent work by a dependency have an attribute for that dependency's version.
17 | * Spans should include attributes identifying underlying infrastructure:
18 |     * Hostname / FQDN
19 |     * Container name, if appropriate
20 |     * Runtime version
21 |     * Application server version, if applicable
22 |     * Region or availability zone
23 | * Attributes are namespaced where appropriate (i.e., to prevent collisions between key names where the semantic meaning of the key differs between services in a request).
24 | * Attributes with numerical values should include the unit of measurement in the key name (i.e, payload_size_kb versus payload_size).
25 | * Attributes should not contain any PII.
26 | 
27 | ## Events
28 | * Useful and descriptive event messages that would be useful for upstream or downstream service users should be added:
29 |     * Request-response payloads (sanitized)
30 |     * Stack traces, exceptions, and error messages
31 | * Long-running operations (such as waiting for a mutex) should be wrapped in events; one when the operation begins, and one when it ends.


--------------------------------------------------------------------------------