Skip to main content

Logs

LogLines​

Version: 0.0

Properties and field requirements​

  • Time field - required
    • The first time field with the name timestamp is the time field.
    • it must be non nullable
  • Body field - required
    • The first string field with the name body is the body field.
    • it must be non nullable
  • Severity field - optional
    • The first string field with the name severity is the severity field.
    • Represents the severity/level of the log line
    • If no severity field is found, consumers/client will decide the log level. Example: logs visualization will try to parse the message field and determine the log level
    • Log level can be one of the values specified in the docs here
  • ID field - optional
    • The first string field with the name id is the id field.
    • Unique identifier of the log line
  • Labels field - optional
    • The first field with the name labels is the labels field.
    • This field represents additional information about the log line.
    • Field type must be json raw message type. Example value: {}, {"hello": "world", "foo": 123.45, "bar": ["yellow","red"], "baz": { "name": "alice" }}
      • Value should be represented with Record<string,any> type in javascript.
  • LabelTypes field - optional
    • The first field with the name labelTypes is the label types field.
    • This field represents the groupings of the labels.
    • Field type must be json raw message type. Example value: {}, {"hello":"Field", "foo": "Metadata", "bar": "ArrayField" , "baz" : "Field"}
      • Value should be represented with Record<string,string> type in javascript.
    • As of Grafana 12.4 label types are used in Log Details in the Logs Panel to group related labels.
    • Note: The data source must fulfill the DataSourceWithLogsLabelTypesSupport interface, otherwise all labels will display in the default "Fields" category

Any other field is ignored by logs visualisation.

Example​

Following is an example of a logs frame in go

data.NewFrame(
    "logs",
    data.NewField("timestamp", nil, []time.Time{time.UnixMilli(1645030244810), time.UnixMilli(1645030247027), time.UnixMilli(1645030247027)}),
    data.NewField("body", nil, []string{"message one", "message two", "message three"}),
    data.NewField("severity", nil, []string{"critical", "error", "warning"}),
    data.NewField("id", nil, []string{"xxx-001", "xyz-002", "111-003"}),
    data.NewField("labels", nil, []json.RawMessage{[]byte(`{}`), []byte(`{"hello":"world"}`), []byte(`{"hello": "world", "foo": 123.45, "bar": ["yellow","red"], "baz": { "name": "alice" }}`)}),
    data.NewField("labelTypes", nil, []json.RawMessage{[]byte(`{}`), []byte(`{"hello": "Field"}`), []byte(`{"hello": "Field", "foo": "Metadata", "bar": "ArrayField", "baz": "Field"}`)}),
)

the same can be represented as

Name: timestamp
Type: []time.Time		Name: body
Type: []string		Name: severity
Type: []*string		Name: id
Type: []*string		Name: labels
Type: []json.RawMessage		Name: labelTypes
Type: []json.RawMessage
2022-02-16 16:50:44.810 +0000 GMTmessage onecriticalxxx-001{}{}
2022-02-16 16:50:47.027 +0000 GMTmessage twoerrorxyz-002{"hello": "world"}{"hello": "Field"}
2022-02-16 16:50:47.027 +0000 GMTmessage threewarning111-003{"hello": "world", "foo": 123.45, "bar": ["yellow","red"], "baz": { "name": "alice" }}{"hello":"Field", "foo": "Number Field", "bar": "ArrayField", "baz": "Field"}

Meta data requirements​

  • Frame type must be set to FrameTypeLogLines/log-lines
  • Frame meta can optionally specify preferredVisualisationType:logs as metadata. Without this property, explore page will be rendering the logs data as table instead in logs view

Invalid cases​

  • Frame without time field
  • Frame without string field
  • Frame with field name "tsNs" where the type of the "tsNs" field is not number.