Skip to content

Commit 804754e

Browse files
frristfrrist
authored
Merge pull request #28 from ipfs/fix/update-README
Fix/update readme
2 parents 5e73401 + 0b65b1a commit 804754e

File tree

2 files changed

+93
-109
lines changed

2 files changed

+93
-109
lines changed

‎README.md

+26-43
Original file line numberDiff line numberDiff line change
@@ -28,59 +28,42 @@ Once the pacakge is imported under the name `logging`, an instance of `EventLogg
2828
var log = logging.Logger("subsystem name")
2929
```
3030

31-
It can then be used to emit log messages, either plain printf-style messages at six standard levels or structured messages using `Event`, `EventBegin` and `EventBeginInContext` methods.
31+
It can then be used to emit log messages, either plain printf-style messages at six standard levels or structured messages using `Start`, `StartFromParentState`, `Finish` and `FinishWithErr` methods.
3232

33-
## Examples
33+
## Example
3434

35-
**Event**
36-
```go
37-
log.Event(ctx, "event name", logging.LoggableMap{"metaKey": metaValue})
38-
```
39-
40-
**EventBegin**
41-
42-
In a method with named returns
4335
```go
4436
func (s *Session) GetBlock(ctx context.Context, c *cid.Cid) (blk blocks.Block, err error) {
45-
eip := log.EventBegin(ctx, "Session.GetBlock", c)
46-
defer func() {
47-
if err != nil {
48-
eip.SetError(err)
37+
38+
// Starts Span called "Session.GetBlock", associates with `ctx`
39+
ctx = log.Start(ctx, "Session.GetBlock")
40+
41+
// defer so `blk` and `err` can be evaluated after call
42+
defer func() {
43+
// tag span associated with `ctx`
44+
log.SetTags(ctx, map[string]interface{}{
45+
"cid": c,
46+
"block", blk,
47+
})
48+
// if err is non-nil tag the span with an error
49+
log.FinishWithErr(ctx, err)
50+
}()
51+
52+
if shouldStartSomething() {
53+
// log message on span associated with `ctx`
54+
log.LogKV(ctx, "startSomething", true)
4955
}
50-
eip.Done()
51-
}()
5256
...
5357
}
5458
```
55-
As a one liner
56-
```go
57-
defer log.EventBegin(ctx, "bootstrapDial", ph.ID(), p.ID).Done()
58-
```
59+
## Tracing
5960

60-
**EventBeginInContext**
61+
`go-log` wraps the [opentracing-go](https://github.com/opentracing/opentracing-go) methods - `StartSpan`, `Finish`, `LogKV`, and `SetTag`.
62+
63+
`go-log` implements its own tracer - `loggabletracer` - based on the [basictracer-go](https://github.com/opentracing/basictracer-go) implementation. If there is an active [`WriterGroup`](https://github.com/ipfs/go-log/blob/master/writer/option.go) the `loggabletracer` will [record](https://github.com/ipfs/go-log/blob/master/tracer/recorder.go) span data to the `WriterGroup`. An example of this can be seen in the [`log tail`](https://github.com/ipfs/go-ipfs/blob/master/core/commands/log.go) command of `go-ipfs`.
64+
65+
Third party tracers may be used by calling `opentracing.SetGlobalTracer()` with your desired tracing implementation. An example of this can be seen using the [`go-jaeger-plugin`](https://github.com/ipfs/go-jaeger-plugin) and the `go-ipfs` [tracer plugin](https://github.com/ipfs/go-ipfs/blob/master/plugin/tracer.go)
6166

62-
When an event spans more than one function call
63-
Start and event in the context
64-
```go
65-
func (s *blockService) GetBlocks(ctx context.Context, ks []*cid.Cid) <-chan blocks.Block {
66-
ctx = log.EventBeginInContext(ctx, "BlockService.GetBlocks")
67-
return getBlocks(ctx, ks, s.blockstore, s.exchange)
68-
}
69-
```
70-
Finish the event later
71-
```go
72-
func getBlocks(ctx context.Context, ks []*cid.Cid, bs blockstore.Blockstore, f exchange.Fetcher) <-chan blocks.Block {
73-
...
74-
go func() {
75-
defer logging.MaybeFinishEvent(ctx)
76-
...
77-
select {
78-
case out <- hit:
79-
case <-ctx.Done():
80-
return
81-
}
82-
}
83-
```
8467
## Contribute
8568

8669
Feel free to join in. All welcome. Open an [issue](https://github.com/ipfs/go-log/issues)!

‎log.go

+67-66
Original file line numberDiff line numberDiff line change
@@ -60,19 +60,86 @@ type EventLogger interface {
6060
// DEPRECATED
6161
EventBegin(ctx context.Context, event string, m ...Loggable) *EventInProgress
6262

63+
// Start starts an opentracing span with `name`, using
64+
// any Span found within `ctx` as a ChildOfRef. If no such parent could be
65+
// found, Start creates a root (parentless) Span.
66+
//
67+
// The return value is a context.Context object built around the
68+
// returned Span.
69+
//
70+
// Example usage:
71+
//
72+
// SomeFunction(ctx context.Context, ...) {
73+
// ctx := log.Start(ctx, "SomeFunction")
74+
// defer log.Finish(ctx)
75+
// ...
76+
// }
6377
Start(ctx context.Context, name string) context.Context
78+
79+
// StartFromParentState starts an opentracing span with `name`, using
80+
// any Span found within `ctx` as a ChildOfRef. If no such parent could be
81+
// found, StartSpanFromParentState creates a root (parentless) Span.
82+
//
83+
// StartFromParentState will attempt to deserialize a SpanContext from `parent`,
84+
// using any Span found within to continue the trace
85+
//
86+
// The return value is a context.Context object built around the
87+
// returned Span.
88+
//
89+
// An error is returned when `parent` cannot be deserialized to a SpanContext
90+
//
91+
// Example usage:
92+
//
93+
// SomeFunction(ctx context.Context, bParent []byte) {
94+
// ctx := log.StartFromParentState(ctx, "SomeFunction", bParent)
95+
// defer log.Finish(ctx)
96+
// ...
97+
// }
6498
StartFromParentState(ctx context.Context, name string, parent []byte) (context.Context, error)
6599

100+
// Finish completes the span associated with `ctx`.
101+
//
102+
// Finish() must be the last call made to any span instance, and to do
103+
// otherwise leads to undefined behavior.
104+
// Finish will do its best to notify (log) when used in correctly
105+
// .e.g called twice, or called on a spanless `ctx`
66106
Finish(ctx context.Context)
107+
108+
// FinishWithErr completes the span associated with `ctx` and also calls
109+
// SetErr if `err` is non-nil
110+
//
111+
// FinishWithErr() must be the last call made to any span instance, and to do
112+
// otherwise leads to undefined behavior.
113+
// FinishWithErr will do its best to notify (log) when used in correctly
114+
// .e.g called twice, or called on a spanless `ctx`
67115
FinishWithErr(ctx context.Context, err error)
68116

117+
// SetErr tags the span associated with `ctx` to reflect an error occured, and
118+
// logs the value `err` under key `error`.
69119
SetErr(ctx context.Context, err error)
70120

121+
// LogKV records key:value logging data about an event stored in `ctx`
122+
// Eexample:
123+
// log.LogKV(
124+
// "error", "resolve failure",
125+
// "type", "cache timeout",
126+
// "waited.millis", 1500)
71127
LogKV(ctx context.Context, alternatingKeyValues ...interface{})
72128

129+
// SetTag tags key `k` and value `v` on the span associated with `ctx`
73130
SetTag(ctx context.Context, key string, value interface{})
131+
132+
// SetTags tags keys from the `tags` maps on the span associated with `ctx`
133+
// Example:
134+
// log.SetTags(ctx, map[string]{
135+
// "type": bizStruct,
136+
// "request": req,
137+
// })
74138
SetTags(ctx context.Context, tags map[string]interface{})
75139

140+
// SerializeContext takes the SpanContext instance stored in `ctx` and Seralizes
141+
// it to bytes. An error is returned if the `ctx` cannot be serialized to
142+
// a bytes array
76143
SerializeContext(ctx context.Context) ([]byte, error)
77144
}
78145

@@ -100,46 +167,12 @@ type eventLogger struct {
100167
// TODO add log-level
101168
}
102169

103-
// Start starts an opentracing span with `operationName`, using
104-
// any Span found within `ctx` as a ChildOfRef. If no such parent could be
105-
// found, StartSpanFromContext creates a root (parentless) Span.
106-
//
107-
// The return value is a context.Context object built around the
108-
// returned Span.
109-
//
110-
// Example usage:
111-
//
112-
// SomeFunction(ctx context.Context, ...) {
113-
// ctx := log.Start(ctx, "SomeFunction")
114-
// defer log.Finish(ctx)
115-
// ...
116-
// }
117170
func (el *eventLogger) Start(ctx context.Context, operationName string) context.Context {
118171
span, ctx := opentrace.StartSpanFromContext(ctx, operationName)
119172
span.SetTag("system", el.system)
120173
return ctx
121174
}
122175

123-
// TODO: need clearer examples and description
124-
// StartFromParentState starts an opentracing span with `operationName`, using
125-
// any Span found within `ctx` as a ChildOfRef. If no such parent could be
126-
// found, StartSpanFromContext creates a root (parentless) Span.
127-
//
128-
// StartFromParentState will attempt to deserialize a SpanContext from `parent`,
129-
// using any Span found within to continue the trace
130-
//
131-
// The return value is a context.Context object built around the
132-
// returned Span.
133-
//
134-
// An error is returned when `parent` cannot be deserialized to a SpanContext
135-
//
136-
// Example usage:
137-
//
138-
// SomeFunction(ctx context.Context, ...) {
139-
// ctx := log.StartFromParentState(ctx, "SomeFunction", bParent)
140-
// defer log.Finish(ctx)
141-
// ...
142-
// }
143176
func (el *eventLogger) StartFromParentState(ctx context.Context, operationName string, parent []byte) (context.Context, error) {
144177
sc, err := deserializeContext(parent)
145178
if err != nil {
@@ -152,8 +185,6 @@ func (el *eventLogger) StartFromParentState(ctx context.Context, operationName s
152185
return ctx, nil
153186
}
154187

155-
// SerializeContext takes the SpanContext instance stored in `ctx`, and Seralizes
156-
// it to bytes.
157188
func (el *eventLogger) SerializeContext(ctx context.Context) ([]byte, error) {
158189
gTracer := opentrace.GlobalTracer()
159190
b := make([]byte, 0)
@@ -165,12 +196,6 @@ func (el *eventLogger) SerializeContext(ctx context.Context) ([]byte, error) {
165196
return carrier.Bytes(), nil
166197
}
167198

168-
// LogKV records key:value logging data about an event stored in `ctx`
169-
// Eexample:
170-
// log.LogKV(
171-
// "error", "resolve failure",
172-
// "type", "cache timeout",
173-
// "waited.millis", 1500)
174199
func (el *eventLogger) LogKV(ctx context.Context, alternatingKeyValues ...interface{}) {
175200
span := opentrace.SpanFromContext(ctx)
176201
if span == nil {
@@ -181,7 +206,6 @@ func (el *eventLogger) LogKV(ctx context.Context, alternatingKeyValues ...interf
181206
span.LogKV(alternatingKeyValues...)
182207
}
183208

184-
// SetTag tags key `k` and value `v` on the span associated with `ctx`
185209
func (el *eventLogger) SetTag(ctx context.Context, k string, v interface{}) {
186210
span := opentrace.SpanFromContext(ctx)
187211
if span == nil {
@@ -192,12 +216,6 @@ func (el *eventLogger) SetTag(ctx context.Context, k string, v interface{}) {
192216
span.SetTag(k, v)
193217
}
194218

195-
// SetTags tags keys from the `tags` maps on the span associated with `ctx`
196-
// Example:
197-
// log.SetTags(ctx, map[string]{
198-
// "tag": bizStruct,
199-
// "bar": fizStruct,
200-
// })
201219
func (el *eventLogger) SetTags(ctx context.Context, tags map[string]interface{}) {
202220
span := opentrace.SpanFromContext(ctx)
203221
if span == nil {
@@ -210,8 +228,6 @@ func (el *eventLogger) SetTags(ctx context.Context, tags map[string]interface{})
210228
}
211229
}
212230

213-
// SetErr tags the span associated with `ctx` to reflect an error occured, and
214-
// logs the value `err` under key `error`
215231
func (el *eventLogger) SetErr(ctx context.Context, err error) {
216232
span := opentrace.SpanFromContext(ctx)
217233
if span == nil {
@@ -227,13 +243,6 @@ func (el *eventLogger) SetErr(ctx context.Context, err error) {
227243
span.LogKV("error", err.Error())
228244
}
229245

230-
// Finish completes the span associated with `ctx` by
231-
// setting the end timestamp and finalizing the Span state.
232-
//
233-
// Finish() must be the last call made to any span instance, and to do
234-
// otherwise leads to undefined behavior.
235-
// Finish will do its best to notify (log) when used in correctly
236-
// .e.g called twice, or called on a spanless `ctx`
237246
func (el *eventLogger) Finish(ctx context.Context) {
238247
span := opentrace.SpanFromContext(ctx)
239248
if span == nil {
@@ -244,14 +253,6 @@ func (el *eventLogger) Finish(ctx context.Context) {
244253
span.Finish()
245254
}
246255

247-
// FinishWithErr completes the span associated with `ctx` by
248-
// setting the end timestamp and finalizing the Span state, in addition to
249-
// calling the `SetErr` method first
250-
//
251-
// FinishWithErr() must be the last call made to any span instance, and to do
252-
// otherwise leads to undefined behavior.
253-
// FinishWithErr will do its best to notify (log) when used in correctly
254-
// .e.g called twice, or called on a spanless `ctx`
255256
func (el *eventLogger) FinishWithErr(ctx context.Context, err error) {
256257
el.SetErr(ctx, err)
257258
el.Finish(ctx)

0 commit comments

Comments
 (0)