class Google::Cloud::Logging::Entry

# Entry

An individual entry in a log.

Each log entry is composed of metadata and a payload. The metadata includes standard information used by Stackdriver Logging, such as when the entry was created and where it came from. The payload is the event record. Traditionally this is a message string, but in Stackdriver Logging it can also be a JSON or protocol buffer object. A single log can have entries with different payload types.

A log is a named collection of entries. Logs can be produced by Google Cloud Platform services, by third-party services, or by your applications. For example, the log `compute.googleapis.com/activity_log` is produced by Google Compute Engine. Logs are simply referenced by name in google-cloud. There is no `Log` type in google-cloud or `Log` resource in the Stackdriver Logging API.

@see cloud.google.com/logging/docs/view/logs_index List of Log

Types

@example

require "google/cloud/logging"

logging = Google::Cloud::Logging.new

entry = logging.entry payload: "Job started.", log_name: "my_app_log"
entry.resource.type = "gae_app"
entry.resource.labels[:module_id] = "1"
entry.resource.labels[:version_id] = "20150925t173233"

logging.write_entries entry

@example Provide a hash to write a JSON payload to the log:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new

payload = { "stats" => { "a" => 8, "b" => 12.5} }
entry = logging.entry payload: payload, log_name: "my_app_log"
entry.resource.type = "gae_app"
entry.resource.labels[:module_id] = "1"
entry.resource.labels[:version_id] = "20150925t173233"

logging.write_entries entry

Attributes

http_request[R]

Information about the HTTP request associated with this log entry, if applicable. @return [Google::Cloud::Logging::Entry::HttpRequest]

insert_id[RW]

A unique ID for the log entry. If you provide this field, the logging service considers other log entries in the same log with the same ID as duplicates which can be removed. If omitted, Stackdriver Logging will generate a unique ID for this log entry. @return [String]

labels[RW]

A set of user-defined data that provides additional information about the log entry. @return [Hash]

log_name[RW]

The resource name of the log to which this log entry belongs. The format of the name is `projects/<project-id>/logs/<log-id>`. e.g. `projects/my-projectid/logs/my_app_log` and `projects/1234567890/logs/library.googleapis.com%2Fbook_log`

The log ID part of resource name must be less than 512 characters long and can only include the following characters: upper and lower case alphanumeric characters: `[A-Za-z0-9]`; and punctuation characters: forward-slash (`/`), underscore (`_`), hyphen (`-`), and period (`.`). Forward-slash (`/`) characters in the log ID must be URL-encoded.

operation[R]

Information about an operation associated with the log entry, if applicable. @return [Google::Cloud::Logging::Entry::Operation]

payload[RW]

The log entry payload, represented as either a string, a hash (JSON), or a hash (protocol buffer). @return [String, Hash]

resource[RW]

The monitored resource associated with this log entry. Example: a log entry that reports a database error would be associated with the monitored resource designating the particular database that reported the error. @return [Google::Cloud::Logging::Resource]

severity[RW]

The severity level of the log entry. The default value is `:DEFAULT`. @return [Symbol]

source_location[R]

Source code location information associated with the log entry, if any. @return [Google::Cloud::Logging::Entry::SourceLocation]

timestamp[RW]

The time the event described by the log entry occurred. If omitted, Stackdriver Logging will use the time the log entry is written. @return [Time]

trace[RW]

Resource name of the trace associated with the log entry, if any. If it contains a relative resource name, the name is assumed to be relative to `//tracing.googleapis.com`. Example: `projects/my-projectid/traces/06796866738c859f2f19b7cfb3214824` Optional. @return [String]

trace_sampled[RW]

The sampling decision of the trace associated with the log entry. Optional. A `true` value means that the trace resource name in the `trace` field was sampled for storage in a trace backend. A `false` means that the trace was not sampled for storage when this log entry was written, or the sampling decision was unknown at the time. A non-sampled `trace` value is still useful as a request correlation identifier. The default is `false`. @return [Boolean]

Public Class Methods

extract_payload(grpc) click to toggle source

@private Extract payload data from Google API Client object.

# File lib/google/cloud/logging/entry.rb, line 515
def self.extract_payload grpc
  grpc.proto_payload || grpc.json_payload || grpc.text_payload
end
extract_timestamp(grpc) click to toggle source

@private Get a Time object from a Google::Protobuf::Timestamp object.

# File lib/google/cloud/logging/entry.rb, line 521
def self.extract_timestamp grpc
  return nil if grpc.timestamp.nil?
  Time.at grpc.timestamp.seconds, Rational(grpc.timestamp.nanos, 1000)
end
from_grpc(grpc) click to toggle source

@private New Entry from a Google::Cloud::Logging::V2::LogEntry object.

# File lib/google/cloud/logging/entry.rb, line 448
def self.from_grpc grpc
  return new if grpc.nil?
  new.tap do |e|
    e.log_name = grpc.log_name
    e.timestamp = extract_timestamp grpc
    e.severity = grpc.severity
    e.insert_id = grpc.insert_id
    e.labels = Convert.map_to_hash grpc.labels
    e.payload = extract_payload grpc
    e.instance_variable_set :@resource,
                            Resource.from_grpc(grpc.resource)
    e.instance_variable_set :@http_request,
                            HttpRequest.from_grpc(grpc.http_request)
    e.instance_variable_set :@operation,
                            Operation.from_grpc(grpc.operation)
    e.trace = grpc.trace
    e.instance_variable_set :@source_location,
                            SourceLocation.from_grpc(
                              grpc.source_location
                            )
    e.trace_sampled = grpc.trace_sampled
  end
end
insert_id() click to toggle source

Generate a pseudo-random, 16-character ID suitable for use as the log entry's {#insert_id}.

@return [String]

@example

require "google/cloud/logging"

insert_id = Google::Cloud::Logging::Entry.insert_id
# File lib/google/cloud/logging/entry.rb, line 85
def self.insert_id
  rand(36**16).to_s 36
end
new() click to toggle source

Create a new Entry instance. The {#resource} attribute is pre-populated with a new {Google::Cloud::Logging::Resource} instance. See also {Google::Cloud::Logging::Project#entry}.

# File lib/google/cloud/logging/entry.rb, line 93
def initialize
  @labels = {}
  @resource = Resource.new
  @http_request = HttpRequest.new
  @operation = Operation.new
  @severity = :DEFAULT
  @source_location = SourceLocation.new
  @insert_id = Entry.insert_id
end

Public Instance Methods

alert!() click to toggle source

Sets the severity level to `:ALERT`.

@example

require "google/cloud/logging"

logging = Google::Cloud::Logging.new

entry = logging.entry
entry.severity #=> :DEFAULT
entry.alert!
entry.alert? #=> true
entry.severity #=> :ALERT
# File lib/google/cloud/logging/entry.rb, line 323
def alert!
  self.severity = :ALERT
end
alert?() click to toggle source

Returns `true` if the severity level is `:ALERT`.

# File lib/google/cloud/logging/entry.rb, line 305
def alert?
  severity == :ALERT
end
append_payload(grpc) click to toggle source

@private Adds the payload data to a Google::Cloud::Logging::V2::LogEntry object.

# File lib/google/cloud/logging/entry.rb, line 499
def append_payload grpc
  grpc.proto_payload = nil
  grpc.json_payload  = nil
  grpc.text_payload  = nil

  if payload.is_a? Google::Protobuf::Any
    grpc.proto_payload = payload
  elsif payload.respond_to? :to_hash
    grpc.json_payload = Convert.hash_to_struct payload.to_hash
  else
    grpc.text_payload = payload.to_s
  end
end
critical!() click to toggle source

Sets the severity level to `:CRITICAL`.

@example

require "google/cloud/logging"

logging = Google::Cloud::Logging.new

entry = logging.entry
entry.severity #=> :DEFAULT
entry.critical!
entry.critical? #=> true
entry.severity #=> :CRITICAL
# File lib/google/cloud/logging/entry.rb, line 299
def critical!
  self.severity = :CRITICAL
end
critical?() click to toggle source

Returns `true` if the severity level is `:CRITICAL`.

# File lib/google/cloud/logging/entry.rb, line 281
def critical?
  severity == :CRITICAL
end
debug!() click to toggle source

Sets the severity level to `:DEBUG`.

@example

require "google/cloud/logging"

logging = Google::Cloud::Logging.new

entry = logging.entry
entry.severity #=> :DEFAULT
entry.debug!
entry.debug? #=> true
entry.severity #=> :DEBUG
# File lib/google/cloud/logging/entry.rb, line 179
def debug!
  self.severity = :DEBUG
end
debug?() click to toggle source

Returns `true` if the severity level is `:DEBUG`.

# File lib/google/cloud/logging/entry.rb, line 161
def debug?
  severity == :DEBUG
end
default!() click to toggle source

Sets the severity level to `:DEFAULT`.

@example

require "google/cloud/logging"

logging = Google::Cloud::Logging.new

entry = logging.entry
entry.severity = :DEBUG
entry.default!
entry.default? #=> true
entry.severity #=> :DEFAULT
# File lib/google/cloud/logging/entry.rb, line 155
def default!
  self.severity = :DEFAULT
end
default?() click to toggle source

Returns `true` if the severity level is `:DEFAULT`.

# File lib/google/cloud/logging/entry.rb, line 137
def default?
  severity == :DEFAULT
end
emergency!() click to toggle source

Sets the severity level to `:EMERGENCY`.

@example

require "google/cloud/logging"

logging = Google::Cloud::Logging.new

entry = logging.entry
entry.severity #=> :DEFAULT
entry.emergency!
entry.emergency? #=> true
entry.severity #=> :EMERGENCY
# File lib/google/cloud/logging/entry.rb, line 347
def emergency!
  self.severity = :EMERGENCY
end
emergency?() click to toggle source

Returns `true` if the severity level is `:EMERGENCY`.

# File lib/google/cloud/logging/entry.rb, line 329
def emergency?
  severity == :EMERGENCY
end
empty?() click to toggle source

@private Determines if the Entry has any data.

# File lib/google/cloud/logging/entry.rb, line 411
def empty?
  log_name.nil? &&
    timestamp.nil? &&
    (labels.nil? || labels.empty?) &&
    payload.nil? &&
    resource.empty? &&
    http_request.empty? &&
    operation.empty? &&
    trace.nil? &&
    source_location.empty? &&
    trace_sampled.nil?
end
error!() click to toggle source

Sets the severity level to `:ERROR`.

@example

require "google/cloud/logging"

logging = Google::Cloud::Logging.new

entry = logging.entry
entry.severity #=> :DEFAULT
entry.error!
entry.error? #=> true
entry.severity #=> :ERROR
# File lib/google/cloud/logging/entry.rb, line 275
def error!
  self.severity = :ERROR
end
error?() click to toggle source

Returns `true` if the severity level is `:ERROR`.

# File lib/google/cloud/logging/entry.rb, line 257
def error?
  severity == :ERROR
end
info!() click to toggle source

Sets the severity level to `:INFO`.

@example

require "google/cloud/logging"

logging = Google::Cloud::Logging.new

entry = logging.entry
entry.severity #=> :DEFAULT
entry.info!
entry.info? #=> true
entry.severity #=> :INFO
# File lib/google/cloud/logging/entry.rb, line 203
def info!
  self.severity = :INFO
end
info?() click to toggle source

Returns `true` if the severity level is `:INFO`.

# File lib/google/cloud/logging/entry.rb, line 185
def info?
  severity == :INFO
end
labels_grpc() click to toggle source

@private Formats the labels so they can be saved to a Google::Cloud::Logging::V2::LogEntry object.

# File lib/google/cloud/logging/entry.rb, line 487
def labels_grpc
  return {} if labels.nil?
  # Coerce symbols to strings
  Hash[labels.map do |k, v|
    v = String(v) if v.is_a? Symbol
    [String(k), v]
  end]
end
notice!() click to toggle source

Sets the severity level to `:NOTICE`.

@example

require "google/cloud/logging"

logging = Google::Cloud::Logging.new

entry = logging.entry
entry.severity #=> :DEFAULT
entry.notice!
entry.notice? #=> true
entry.severity #=> :NOTICE
# File lib/google/cloud/logging/entry.rb, line 227
def notice!
  self.severity = :NOTICE
end
notice?() click to toggle source

Returns `true` if the severity level is `:NOTICE`.

# File lib/google/cloud/logging/entry.rb, line 209
def notice?
  severity == :NOTICE
end
timestamp_grpc() click to toggle source

@private Formats the timestamp as a Google::Protobuf::Timestamp object.

# File lib/google/cloud/logging/entry.rb, line 475
def timestamp_grpc
  return nil if timestamp.nil?
  # TODO: ArgumentError if timestamp is not a Time object?
  Google::Protobuf::Timestamp.new(
    seconds: timestamp.to_i,
    nanos:   timestamp.nsec
  )
end
to_grpc() click to toggle source

@private Exports the Entry to a Google::Cloud::Logging::V2::LogEntry object.

# File lib/google/cloud/logging/entry.rb, line 426
def to_grpc
  grpc = Google::Cloud::Logging::V2::LogEntry.new(
    log_name:        log_name.to_s,
    timestamp:       timestamp_grpc,
    # TODO: verify severity is the correct type?
    severity:        severity,
    insert_id:       insert_id.to_s,
    labels:          labels_grpc,
    resource:        resource.to_grpc,
    http_request:    http_request.to_grpc,
    operation:       operation.to_grpc,
    trace:           trace.to_s,
    source_location: source_location.to_grpc,
    trace_sampled:   !(!trace_sampled)
  )
  # Add payload
  append_payload grpc
  grpc
end
warning!() click to toggle source

Sets the severity level to `:WARNING`.

@example

require "google/cloud/logging"

logging = Google::Cloud::Logging.new

entry = logging.entry
entry.severity #=> :DEFAULT
entry.warning!
entry.warning? #=> true
entry.severity #=> :WARNING
# File lib/google/cloud/logging/entry.rb, line 251
def warning!
  self.severity = :WARNING
end
warning?() click to toggle source

Returns `true` if the severity level is `:WARNING`.

# File lib/google/cloud/logging/entry.rb, line 233
def warning?
  severity == :WARNING
end