Categorygithub.com/sourcegraph/appdash
modulepackage
0.0.0-20211028080628-e2786a622600
Repository: https://github.com/sourcegraph/appdash.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
24
Dependents
0
Files
2k SLOC

# README

appdash (view on Sourcegraph)

Appdash is an application tracing system for Go, based on Google's Dapper and Twitter's Zipkin.

Appdash allows you to trace the end-to-end handling of requests and operations in your application (for perf and debugging). It displays timings and application-specific metadata for each step, and it displays a tree and timeline for each request and its children.

To use appdash, you must instrument your application with calls to an appdash recorder. You can record any type of event or operation. Recorders and schemas for HTTP (client and server) and SQL are provided, and you can write your own.

Usage

To install appdash, run:

go get -u sourcegraph.com/sourcegraph/appdash/cmd/...

A standalone example using Negroni and Gorilla packages is available in the examples/cmd/webapp folder.

A demo / pure net/http application (which is slightly more verbose) is also available at cmd/appdash/example_app.go, and it can be ran easily using appdash demo on the command line.

Community

Questions or comments? Join us on #sourcegraph in the Gophers slack!

Development

Appdash uses vfsgen to package HTML templates with the appdash binary for distribution. This means that if you want to modify the template data in traceapp/tmpl you can first build using the dev build tag, which makes the template data be reloaded from disk live.

After you're finished making changes to the templates, always run go generate sourcegraph.com/sourcegraph/appdash/traceapp/tmpl so that the data_vfsdata.go file is updated for normal Appdash users that aren't interested in modifying the template data.

Components

Appdash follows the design and naming conventions of Google's Dapper. You should read that paper if you are curious about why certain architectural choices were made.

There are 4 main components/concepts in appdash:

  • Spans: A span refers to an operation and all of its children. For example, an HTTP handler handles a request by calling other components in your system, which in turn make various API and DB calls. The HTTP handler's span includes all downstream operations and their descendents; likewise, each downstream operation is its own span and has its own descendents. In this way, appdash constructs a tree of all of the operations that occur during the handling of the HTTP request.
  • Event: Your application records the various operations it performs (in the course of handling a request) as Events. Events can be arbitrary messages or metadata, or they can be structured event types defined by a Go type (such as an HTTP ServerEvent or an SQLEvent).
  • Recorder: Your application uses a Recorder to send events to a Collector (see below). Each Recorder is associated with a particular span in the tree of operations that are handling a particular request, and all events sent via a Recorder are automatically associated with that context.
  • Collector: A Collector receives Annotations (which are the encoded form of Events) sent by a Recorder. Typically, your application's Recorder talks to a local Collector (created with NewRemoteCollector. This local Collector forwards data to a remote appdash server (created with NewServer that combines traces from all of the services that compose your application. The appdash server in turn runs a Collector that listens on the network for this data, and it then stores what it receives.

Language Support

Appdash has clients available for Go, Python (see python/ subdir) and Ruby (see https://github.com/bsm/appdash-rb).

OpenTracing Support

Appdash supports the OpenTracing API. Please see the opentracing subdir for the Go implementation, or see the GoDoc for API documentation.

Acknowledgments

appdash was influenced by, and uses code from, Coda Hale's lunk.

# Packages

No description provided by the author
No description provided by the author
Package httptrace implements support for tracing HTTP applications.
Package opentracing provides an Appdash implementation of the OpenTracing API.
Package sqltrace implements utility types for tracing SQL queries.
Package traceapp implements the Appdash web UI.

# Functions

Log returns an Event whose timestamp is the current time that contains only a human-readable message.
LogWithTimestamp returns an Event with an explicit timestamp that contains only a human readable message.
MarshalEvent marshals an event into annotations.
Msg returns an Event that contains only a human-readable message.
MultiQueryer returns a Queryer whose Traces method returns a union of all traces across each queryer.
MultiStore returns a Store whose operations occur on the multiple given stores.
NewChunkedCollector is shorthand for: c := &ChunkedCollector{ Collector: c, MinInterval: 500 * time.Millisecond, FlushTimeout: 2 * time.Second, MaxQueueSize: 32 * 1024 * 1024, // 32 MB Log: log.New(os.Stderr, "appdash: ", log.LstdFlags), } .
NewLocalCollector returns a Collector that writes directly to a Store.
NewMemoryStore creates a new in-memory store.
NewRecorder creates a new recorder for the given span and collector.
NewRemoteCollector creates a collector that sends data to a collector server (created with NewServer).
NewRootSpanID generates a new span ID for a root span.
NewServer creates and starts a new server that listens for spans and annotations on l and adds them to the collector c.
NewSpanID returns a new ID for an span which is the child of the given parent ID.
NewTLSRemoteCollector creates a RemoteCollector that uses TLS.
ParseID parses the given string as a hexadecimal string.
ParseSpanID parses the given string as a slash-separated set of parameters.
PersistEvery persists s's data to a file periodically.
RegisterEvent registers an event type for use with UnmarshalEvents.
SpanName returns an Event containing a human readable Span name.
UnmarshalEvent unmarshals annotations into an event.
UnmarshalEvents unmarshals all events found in anns into events.

# Constants

No description provided by the author
SpanIDDelimiter is the delimiter used to concatenate an SpanID's components.

# Variables

ErrBadSpanID is returned when the span ID cannot be parsed.
ErrQueueDropped is the error returns by ChunkedCollector.Flush and ChunkedCollector.Collect when the internal queue has grown too large and has been subsequently dropped.
ErrTraceNotFound is returned by Store.GetTrace when no trace is found with the given ID.

# Structs

AggregatedResult represents a set of traces that were aggregated together by root span name to produce some useful metrics (average trace time, minimum time, a link to the slowest traces, etc).
An Annotation is an arbitrary key-value property on a span.
ChunkedCollector groups annotations together that have the same span and calls its underlying collector's Collect method with the chunked data periodically, instead of immediately.
A CollectorServer listens for spans and annotations and adds them to a local collector.
An EventSchemaUnmarshalError is when annotations are attempted to be unmarshaled into an event object that does not match any of the schemas in the annotations.
A LimitStore wraps another store and deletes the oldest trace when the number of traces reaches the capacity (Max).
A MemoryStore is an in-memory Store that also implements the PersistentStore interface.
A RecentStore wraps another store and deletes old traces after a specified amount of time.
A Recorder is associated with a span and records annotations on the span by sending them to a collector.
A RemoteCollector sends data to a collector server (created with NewServer).
Span is a span ID and its annotations.
A SpanID refers to a single span.
A SpanNameEvent event sets a span's name.
Timespan is an event that satisfies the appdash.TimespanEvent interface.
A Trace is a tree of spans.
TraceOpts bundles the options used for list of traces.

# Interfaces

Aggregator is a type of store that can aggregate its trace data and return results about it.
A Collector collects events that occur in spans.
A DeleteStore is a Store that can delete traces.
An Event is a record of the occurrence of something.
EventMarshaler is the interface implemented by an event that can marshal a representation of itself into annotations.
EventUnmarshaler is the interface implemented by an event that can unmarshal an annotation representation of itself.
ImportantEvent is an event that can describe in particular which annotation keys it finds important.
PersistentStore is a Store that can persist its data and read it back in.
A Queryer indexes spans and makes them queryable.
A Store stores and retrieves spans.
A TimespanEvent is an Event with a start and an end time.
A TimestampedEvent is an Event with a timestamp.

# Type aliases

Annotations is a list of annotations (on a span).
An ID is a unique, uniformly distributed 64-bit ID.