Introspection types for core (#107)

go.mod

@@ -4,6 +4,7 @@ require (
 	github.com/btcsuite/btcd v0.20.1-beta
 	github.com/coreos/go-semver v0.3.0
 	github.com/gogo/protobuf v1.3.1
+	github.com/golang/protobuf v1.3.2
 	github.com/ipfs/go-cid v0.0.4
 	github.com/jbenet/goprocess v0.1.3
 	github.com/libp2p/go-flow-metrics v0.0.3

go.sum

@@ -34,7 +34,10 @@ github.com/golang/groupcache v0.0.0-20190702054246-869f871628b6 h1:ZgQEtGgCBiWRM
 github.com/golang/groupcache v0.0.0-20190702054246-869f871628b6/go.mod h1:cIg4eruTrX1D+g88fzRXU5OdNfaM+9IcxsU14FzY7Hc=
 github.com/golang/mock v1.1.1/go.mod h1:oTYuIxOrZwtPieC+H1uAHpcLFnEyAGVDL/k47Jfbm0A=
 github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
+github.com/golang/protobuf v1.3.1 h1:YF8+flBXS5eO826T4nzqPrxfhQThhXl0YzfuUPu4SBg=
 github.com/golang/protobuf v1.3.1/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
+github.com/golang/protobuf v1.3.2 h1:6nsPYzhq5kReh6QImI3k5qWzO4PEbvbIW2cwSfR/6xs=
+github.com/golang/protobuf v1.3.2/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
 github.com/google/go-cmp v0.3.0 h1:crn/baboCvb5fXaQ0IJ1SGTsTVrWpDsCWC8EGETZijY=
 github.com/google/go-cmp v0.3.0/go.mod h1:8QqcDgzrUqlUb/G2PQTWiueGozuR1884gddMywk6iLU=
 github.com/gxed/hashland/keccakpg v0.0.1 h1:wrk3uMNaMxbXiHibbPO4S0ymqJMm41WiudyFSs7UnsU=

host/host.go

@@ -8,6 +8,7 @@ import (
 
 	"github.com/libp2p/go-libp2p-core/connmgr"
 	"github.com/libp2p/go-libp2p-core/event"
+	"github.com/libp2p/go-libp2p-core/introspect"
 	"github.com/libp2p/go-libp2p-core/network"
 	"github.com/libp2p/go-libp2p-core/peer"
 	"github.com/libp2p/go-libp2p-core/peerstore"
@@ -73,3 +74,14 @@ type Host interface {
 	// EventBus returns the hosts eventbus
 	EventBus() event.Bus
 }
+
+// IntrospectableHost is implemented by Host implementations that are
+// introspectable, that is, that expose an introspection server.
+type IntrospectableHost interface {
+
+	// Introspector returns the Introspector instance, with which the caller
+	// can:
+	//  - register data providers.
+	//  - fetch introspection data.
+	Introspector() introspect.Introspector
+}

introspect/doc.go

@@ -0,0 +1,9 @@
+// Package introspect is EXPERIMENTAL. It is subject to heavy change, and it
+// WILL change. For now, it is the simplest implementation to power the
+// proof-of-concept of the libp2p introspection framework.
+//
+// Package introspect contains the abstract skeleton of the introspection system
+// of go-libp2p. It holds the introspection data schema, and the primitives that
+// allow subsystems to register data providers, and clients to fetch the current
+// state of the system.
+package introspect

introspect/introspect.go

@@ -0,0 +1,25 @@
+package introspect
+
+import introspect_pb "github.com/libp2p/go-libp2p-core/introspect/pb"
+
+// ProtoVersion is the current version of the introspection protocol.
+const ProtoVersion uint32 = 1
+
+// EXPERIMENTAL. Introspector allows other sub-systems/modules to register
+// metrics/data providers AND also enables clients to fetch the current state of
+// the system.
+type Introspector interface {
+
+	// EXPERIMENTAL. RegisterDataProviders allows sub-systems/modules to
+	// register callbacks that supply introspection data.
+	RegisterDataProviders(p *DataProviders) error
+
+	// EXPERIMENTAL. FetchFullState returns the full state of the system, by
+	// calling all known data providers and returning a merged cross-cut of the
+	// running system.
+	FetchFullState() (*introspect_pb.State, error)
+
+	// EXPERIMENTAL. ListenAddrs returns the addresses on which the
+	// introspection server endpoint is listening for clients.
+	ListenAddrs() []string
+}

introspect/pb/Makefile

@@ -0,0 +1,11 @@
+PB = $(wildcard *.proto)
+GO = $(PB:.proto=.pb.go)
+
+all: $(GO)
+
+%.pb.go: %.proto
+	protoc --proto_path=$(PWD):$(PWD)/../..:$(GOPATH)/src --gogofaster_out=Mgoogle/protobuf/timestamp.proto=github.com/gogo/protobuf/types:. $<
+
+clean:
+	rm -f *.pb.go
+	rm -f *.go

introspect/pb/introspection.proto

@@ -0,0 +1,296 @@
+syntax = "proto3";
+package introspect.pb;
+
+import "github.com/gogo/protobuf/gogoproto/gogo.proto";
+import "google/protobuf/timestamp.proto";
+
+// Version of schema
+message Version {
+    uint32 number = 1;
+}
+// ResultCounter is a monotonically increasing counter that reports an ok/err breakdown of the total.
+message ResultCounter {
+    uint32 total = 1;
+    uint32 ok = 2;
+    uint32 err = 3;
+}
+
+// Moving totals over sliding time windows. Models sensible time windows,
+// we don't have to populate them all at once.
+//
+// Graphical example:
+//
+// time     past -> present                              an event 16 min ago
+// ======================================================X================>>
+//                                                       |               | 1m
+//                                                       |           |---| 5m
+//                                                       | |-------------| 15m
+//                                          |------------X---------------| 30m
+//            |------------------------------------------X---------------| 60m
+message SlidingCounter {
+    uint32 over_1m      = 1;
+    uint32 over_5m      = 2;
+    uint32 over_15m     = 3;
+    uint32 over_30m     = 4;
+    uint32 over_1hr     = 5;
+    uint32 over_2hr     = 6;
+    uint32 over_4hr     = 7;
+    uint32 over_8hr     = 8;
+    uint32 over_12hr    = 9;
+    uint32 over_24hr    = 10;
+}
+
+// DataGauge reports stats for data traffic in a given direction.
+message DataGauge {
+    // Cumulative bytes.
+    uint64 cum_bytes    = 1;
+    // Cumulative packets.
+    uint64 cum_packets  = 2;
+    // Instantaneous bandwidth measurement (bytes/second).
+    uint64 inst_bw      = 3;
+}
+
+
+// Runtime encapsulates runtime info about a node.
+message Runtime {
+    // e.g. go-libp2p, js-libp2p, rust-libp2p, etc.
+    string implementation   = 1;
+    // e.g. 1.2.3.
+    string version          = 2;
+    // e.g. Windows, Unix, macOS, Chrome, Mozilla, etc.
+    string platform         = 3;
+    // our peer id - the peer id of the host system
+    string peer_id          = 4;
+}
+
+// EndpointPair is a pair of multiaddrs.
+message EndpointPair {
+    // the source multiaddr.
+    string src_multiaddr = 1;
+    // the destination multiaddr.
+    string dst_multiaddr = 2;
+}
+
+// The status of a connection or stream.
+enum Status {
+    ACTIVE  = 0;
+    CLOSED  = 1;
+    OPENING = 2;
+    CLOSING = 3;
+    ERROR   = 4;
+}
+
+// Our role in a connection or stream.
+enum Role {
+    INITIATOR = 0;
+    RESPONDER = 1;
+}
+
+// Traffic encloses data transfer statistics.
+message Traffic {
+    // snapshot of the data in metrics.
+    DataGauge traffic_in    = 1;
+    // snapshot of the data out metrics.
+    DataGauge traffic_out   = 2;
+}
+
+// a list of streams, by reference or inlined.
+message StreamList {
+    // NOTE: only one of the next 2 fields can appear, but proto3
+    // doesn't support combining oneof and repeated.
+    //
+    // streams within this connection by reference.
+    repeated bytes stream_ids   = 1;
+    // streams within this connection by inlining.
+    repeated Stream streams     = 2;
+}
+
+// Connection reports metrics and state of a libp2p connection.
+message Connection {
+    // Timeline contains the timestamps of the well-known milestones of a connection.
+    message Timeline {
+        // the instant when a connection was opened on the wire.
+        google.protobuf.Timestamp open_ts = 1 [(gogoproto.stdtime) = true];
+        // the instant when the upgrade process (handshake, security, multiplexing) finished.
+        google.protobuf.Timestamp upgraded_ts = 2 [(gogoproto.stdtime) = true];
+        // the instant when this connection was terminated.
+        google.protobuf.Timestamp close_ts = 3 [(gogoproto.stdtime) = true];
+    }
+
+    // Attributes encapsulates the attributes of this connection.
+    message Attributes {
+        // the multiplexer being used.
+        string multiplexer  = 1;
+        // the encryption method being used.
+        string encryption   = 2;
+    }
+
+    // the id of this connection, not to be shown in user tooling,
+    // used for (cross)referencing connections (e.g. relay).
+    string id               = 1;
+    // the peer id of the other party.
+    string peer_id          = 2;
+    // the status of this connection.
+    Status status           = 3;
+    // a reference to the transport managing this connection.
+    bytes transport_id      = 4;
+    // the endpoints participating in this connection.
+    EndpointPair endpoints  = 5;
+    // the timeline of the connection, see Connection.Timeline.
+    Timeline timeline       = 6;
+    // our role in this connection.
+    Role role               = 7;
+    // traffic statistics.
+    Traffic traffic         = 8;
+    // properties of this connection.
+    Attributes attribs      = 9;
+    // the instantaneous latency of this connection in nanoseconds.
+    uint64 latency_ns       = 10;
+    // streams within this connection.
+    StreamList streams = 11;
+
+    reserved 12 to 15;
+
+    // if this is a relayed connection, this points to the relaying connection.
+    // a default value here (empty bytes) indicates this is not a relayed connection.
+    oneof relayed_over {
+        string conn_id       = 16;
+        Connection conn     = 17;
+    }
+    // user provided tags.
+    repeated string user_provided_tags  = 99;
+}
+
+// Stream reports metrics and state of a libp2p stream.
+message Stream {
+    message ConnectionRef {
+        oneof connection {
+            // the parent connection inlined.
+            Connection conn = 1;
+            // the parent connection by reference.
+            string conn_id   = 2;
+        }
+    }
+
+    // Timeline contains the timestamps of the well-known milestones of a stream.
+    message Timeline {
+        // the instant when the stream was opened.
+        google.protobuf.Timestamp open_ts = 1 [(gogoproto.stdtime) = true];
+        // the instant when the stream was terminated.
+        google.protobuf.Timestamp close_ts = 2 [(gogoproto.stdtime) = true];
+    }
+
+    // the id of this stream, not to be shown in user tooling,
+    // used for (cross)referencing streams.
+    string id                           = 1;
+    // the protocol pinned to this stream.
+    string protocol                     = 2;
+    // our role in this stream.
+    Role role                           = 3;
+    // traffic statistics.
+    Traffic traffic                     = 4;
+    // the connection this stream is hosted under.
+    ConnectionRef conn                  = 5;
+    // the timeline of the stream, see Stream.Timeline.
+    Timeline timeline                   = 6;
+    // the status of this stream.
+    Status status                       = 7;
+
+    // the instantaneous latency of this stream in nanoseconds.
+    // TODO: this is hard to calculate.
+    uint64 latency_ns                   = 16;
+    // user provided tags.
+    repeated string user_provided_tags  = 99;
+}
+
+// DHT metrics and state.
+message DHT {
+  message Params {
+    // maximum number of requests to perform.
+    uint64 k                    = 1;
+    // concurrency of asynchronous requests.
+    uint64 alpha                = 2;
+    // number of disjoint paths to use.
+    uint64 disjoint_paths       = 3;
+  }
+
+  message Query {
+    // Trigger of the query.
+    enum Trigger {
+        API                     = 0;
+        DISCOVERY               = 1;
+    }
+
+    // Type of the query.
+    enum Type {
+        CONTENT                 = 0;
+        PROVIDER                = 1;
+        VALUE                   = 2;
+    }
+
+    // Status indicating the result of the query
+    enum Result {
+        SUCCESS                 = 0;
+        ERROR                   = 1;
+        TIMEOUT                 = 2;
+        // Pending queries may be absent, depending on data collection
+        PENDING                 = 3;
+    }
+
+    // id of the query; used for internal referencing (<== TODO: confirm this)
+    string id                         = 1;
+    // id of the peer being sought by this query
+    string target_peer_id             = 2;
+    // total time of the query in miliseconds
+    uint64 total_time_ms              = 3;
+    // number of iterative lookups before reaching result
+    uint64 total_steps                = 4;
+    // peers queried.
+    repeated string peer_ids          = 5;
+    // trigger of the query
+    Trigger trigger                   = 6;
+    // type of the query.
+    Type type                         = 7;
+    // status indicating the result of the query
+    Result result                     = 8;
+    // time query was dispatched
+    google.protobuf.Timestamp sent_ts = 9 [(gogoproto.stdtime) = true];
+  }
+
+  // DHT protocol name
+  string protocol                     = 1;
+  // protocol enabled.
+  bool enabled                        = 2;
+  // timestap of start up.
+  google.protobuf.Timestamp start_ts  = 3 [(gogoproto.stdtime) = true];
+  // params of the dht.
+  Params params                       = 4;
+  // queries data
+  repeated Query query                = 5;
+}
+
+// Subsystems encapsulates all instrumented subsystems for a libp2p host.
+message Subsystems {
+  // connections data, source agnostic but currently only supports the Swarm subsystem
+  repeated Connection connections = 1;
+  // the DHT subsystem.
+  DHT dht                         = 2;
+}
+
+// Connections and streams output for a time interval is one of these.
+message State {
+  // Version of this protobuf
+  Version version                      = 1;
+  // system information
+  Runtime runtime                      = 2;
+  // list of connections
+  Subsystems subsystems                = 3;
+  // overall traffic for this peer
+  Traffic traffic                      = 4;
+  // moment this data snapshot and instantaneous values were taken
+  google.protobuf.Timestamp instant_ts = 5;
+  // start of included data collection (cumulative values counted from here)
+  google.protobuf.Timestamp start_ts   = 6;
+  // length of time up to instant_ts covered by this data snapshot
+  uint32 snapshot_duration_ms          = 7;
+}

introspect/providers.go

@@ -0,0 +1,54 @@
+package introspect
+
+import introspect_pb "github.com/libp2p/go-libp2p-core/introspect/pb"
+
+type (
+	// QueryOutput determines the output form of a query result.
+	QueryOutput int
+
+	// ConnectionID represents a connection ID.
+	ConnectionID string
+
+	// StreamID represents a stream ID.
+	StreamID string
+)
+
+const (
+	// QueryOutputFull dictates that we need to resolve the whole object in the
+	// query output.
+	QueryOutputFull QueryOutput = iota
+
+	// QueryOutputList dictates that we need to resolve only the identifiers of
+	// the object in the query output.
+	QueryOutputList
+)
+
+// EXPERIMENTAL. DataProviders enumerates the functions that resolve each entity
+// type. It is used by go-libp2p modules to register callback functions capable
+// of processing entity queries.
+type DataProviders struct {
+	// Runtime is the provider function that returns system runtime information.
+	Runtime func() (*introspect_pb.Runtime, error)
+
+	// Connection is the provider that is called when information about
+	// Connections is required.
+	Connection func(ConnectionQueryParams) ([]*introspect_pb.Connection, error)
+
+	// Stream is the provider that is called when information about Streams is
+	// required.
+	Stream func(StreamQueryParams) (*introspect_pb.StreamList, error)
+
+	// Traffic is the provider that is called when information about network
+	// statistics is required.
+	Traffic func() (*introspect_pb.Traffic, error)
+}
+
+type ConnectionQueryParams struct {
+	Output  QueryOutput
+	Include []ConnectionID
+}
+
+type StreamQueryParams struct {
+	Output  QueryOutput
+	Include []StreamID
+}