94 lines
2.4 KiB
Markdown
94 lines
2.4 KiB
Markdown
# okit
|
|
|
|
Short for "observability kit", `okit` aims to provide an all-in-one solution to application observability.
|
|
|
|
## Why
|
|
|
|
Traditional approaches to observability treat logging, application metrics, and tracing as independent operations, with
|
|
independent data streams. In practice, these elements are more or less all the same, with some minor differences between
|
|
them. Developers often have to choose between logging a message, emitting a metric, or expanding a trace.
|
|
|
|
**Logging**
|
|
|
|
- Used by developers and operators to determine what issues an application may be facing.
|
|
- High cardinality data (errors, stack traces, user id / signature).
|
|
- Often sent to stdout/stderr and can optionally be captured by traditional logging solutions.
|
|
|
|
**Tracing**
|
|
|
|
- Used by developers and operators to troubleshoot performance issues across a set of distributed systems.
|
|
- Medium cardinality data (consistent structure, high variability in tag values)
|
|
- Typically available in real-time to assess product performance.
|
|
|
|
**Metrics**
|
|
|
|
- Used by developers and product managers to determine details about how their product is doing.
|
|
- Medium/High cardinality data (user id / signature, other metadata fields).
|
|
- Typically available in real-time to assess user experience / feature performance.
|
|
|
|
## Usage
|
|
|
|
### Basic
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"context"
|
|
|
|
"go.pitz.tech/okit"
|
|
)
|
|
|
|
func main() {
|
|
var tags []okit.Tag
|
|
|
|
// Metric emission
|
|
okit.Observe("temperature_c", 20.9, tags...)
|
|
|
|
// Multi-dimensional events
|
|
okit.Emit("user_signup", tags...)
|
|
|
|
// Tracing
|
|
ctx, done := okit.Trace(context.Background(), tags...)
|
|
defer done()
|
|
_ = ctx.Err() // not needed, removes unused error
|
|
|
|
// Logging
|
|
okit.Debug("a message used for debugging", tags...)
|
|
okit.Info("an informational message for the user", tags...)
|
|
okit.Warn("a warning indicating an issue with the system", tags...)
|
|
okit.Error("the system encountered an error", tags...)
|
|
}
|
|
```
|
|
|
|
### HTTP
|
|
|
|
`okit` comes with built-in functionality to make it easy to trace HTTP operations.
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"net/http"
|
|
|
|
okithttp "go.pitz.tech/okit/http"
|
|
)
|
|
|
|
func main() {
|
|
// Instrument HTTP Clients
|
|
okithttp.InstrumentClient(http.DefaultClient)
|
|
|
|
// Add reporting endpoints
|
|
mux := http.NewServeMux()
|
|
okithttp.RouteEndpoint(mux, okithttp.NewEndpoint())
|
|
|
|
// Instrument HTTP Handlers
|
|
handler := okithttp.InstrumentHandler(mux)
|
|
err := http.ListenAndServe("0.0.0.0:8080", handler)
|
|
if err != nil {
|
|
panic(err)
|
|
}
|
|
}
|
|
```
|
|
|