X-Ray is logging framework, created for concurrent environment. Central idea - loggers forms
tree structure - starting from xray.ROOT
and then forking to arbitrary level with full
properties inheritance.
Loggers inside framework are named rays. Each forked ray will inherit all properties from parent, including assigned output adapters.
Examples are located in github.com/mono83/xray/example
package
Name | Description |
---|---|
GetRayID() |
Return string ID of current Ray |
GetLogger() |
Returns name of logger, string |
GetMetricPrefix() |
Returns string prefix, that will be attached to all metric events |
GetArguments() |
Returns all arguments (placeholder values), attached to ray as xray.Bucket |
Fork() |
Builds and returns new xray.Ray . New object will inherit all propertes of original, but with new rayID |
WithRayID(string) |
Clones ray and sets provided ID to it |
WithLogger(string) |
Clones ray and sets provided logger name to it |
WithMetricPrefix(string) |
Clones ray and appends metric prefix to it |
With(...xray.Arg) |
Clones ray and appends provided arguments to clone |
On(xray.Handler) |
Attaches Handler , that will receive all logging and metrics event. Registered handler will received events from ray itself and all its forked childs |
Emit(...xray.Event) |
Emits arbitrary xray.Event to ray |
Method | Description |
---|---|
Trace(msg string, args ...xray.Arg) |
Emits log event with xray.TRACE level |
Debug(msg string, args ...xray.Arg) |
Emits log event with xray.DEBUG level |
Info(msg string, args ...xray.Arg) |
Emits log event with xray.INFO level |
Warning(msg string, args ...xray.Arg) |
Emits log event with xray.WARNING level |
Error(msg string, args ...xray.Arg) |
Emits log event with xray.ERROR level |
Alert(msg string, args ...xray.Arg) |
Emits log event with xray.ALERT level |
Critical(msg string, args ...xray.Arg) |
Emits log event with xray.CRITICAL level |
Pass(error) error |
If provided error not nil, emits logging event xray.ERROR level. In any case this methods returns error, provided to it. |
PassS(msg string, err error) error |
If provided error not nil, emits logging event xray.ERROR level with provided string prefix. In any case this methods returns error, provided to it. |
Method | Description |
---|---|
Increment(string, int64, ...xray.Arg) |
Emits metric event with xray.INCREMENT metric type and int64 incrementation value |
Inc(string, ...xray.Arg) |
Emits metric event with xray.INCREMENT metric type and 1 as incrementation value |
Gauge(string, int64, ...xray.Arg) |
Emits metric event with xray.GAUGE metric type and int64 gauge value |
Duration(string, NanoHolder, ...xray.Arg) |
Emits metric event with xray.DURATION metric type. NanoHolder is interface with Nanoseconds() int64 method, that is implemented even in time.Duration structure. |
In general case, arguments a objects, used for message interpolation. In special cases, like Logstash or InfluxDB this arguments can be sent to remote servers.
Argument is pretty simple and described by interface:
// Arg describes ray logging qualifier (argument)
type Arg interface {
// Name returns argument key (name)
Name() string
// Value returns string representation of argument value
Value() string
// Scalar returns raw representation of argument value. It can be scalar value or slice of scalar values.
Scalar() interface{}
}
Predefined arguments are located in github.com/mono83/xray/args
package and it subpackages:
Argument | Name | Scalar | Instantiation |
---|---|---|---|
args.Nil |
any | nil |
Cast from string , that will be used as Name |
args.Error |
"err" |
string |
args.Error{Err: <error value>} |
args.Int |
any | int |
args.Int{N: <string name>, V: <int value>} |
args.Int64 |
any | int64 |
args.Int64{N: <string name>, V: <int64 value>} |
args.Count |
"count" |
int |
Cast from int , that will be used as Value |
args.ID64 |
"id" |
int64 |
Cast from int64 , that will be used as Value |
args.String |
any | string |
args.String{N: <string name>, V: <str value>} |
args.Name |
"name" |
string |
Cast from string , that will be used as Value |
args.Type |
"type" |
string |
Cast from string , that will be used as Value |
args.AppName |
"app" |
string |
Cast from string , that will be used as Value |
args.URL |
"url" |
string |
Cast from string , that will be used as Value |
args.SQL |
"sql" |
string |
Cast from string , that will be used as Value |
args.Delta |
"delta" |
int64 |
Cast from time.Duration . Method Scalar() will returns nanoseconds |
There are also special arguments, that wrap slices
Argument | Name | Values List |
---|---|---|
args.ID64List |
"id" |
[]int64 |
args.NameList |
"name" | []string |
And even more special arguments, that are instantiated by default and located in github.com/mono83/args/env
Argument | Instance | Name | Scalar | Description |
---|---|---|---|---|
env.ArgPID |
env.PID |
"pid" |
int |
Contains process ID (pid) of current application |
env.ArgHostName |
env.HostName |
"hostname" |
string |
Contains host name of machine, this application running on |
env.ArgSystemUser |
env.SystemUser |
"username" |
string |
Contain information of user, invoked application |
Xray is bundled with data exporter, compatible with Prometheus. To enable, attach it to xray.ROOT
or other ray:
import "github.com/mono83/xray/out/prometheus"
// Declaring exporter
prom := prometheus.NewExporter(
nil, // Metrics arguments filtering func
nil, // Default arguments to inject
time.Millisecond, // Time buckets for latency histograms...
10 * time.Millisecond,
50 * time.Millisecond,
100 * time.Millisecond,
250 * time.Millisecons,
500 * time.Millisecond,
time.Second,
10 * time.Second,
)
// Registering on ROOT ray
xray.ROOT.On(prom.Handle)
// Starting HTTP server, that will return metrics on any URL
panic(http.ListenAndServe(":5557", prom))
In addition to served metrics, this exporter also sends its own to diagnose performance issues:
prometheus_exporter_handled
- amount of handled metrics events, counter.prometheus_exporter_render
- amount of render requests, counter.type="writer"
stands for any writer invocation,type="http"
shows only HTTP rendering requests.prometheus_exporter_size
- amount of items in exporter, gauge.type="gauges"
calculates only gauges,type="counters"
is for counters andtype="histogram"
is for histograms.