evtctxget()

Returns the value of a specified property from an event context. Use this function to query metadata such as the counter, creation time, expiration time, and list of collected rows of an event context created by the evtctx command.

Syntax

evtctxget(TOPIC, KEY, FIELD[, HOST])

Parameters

TOPIC
The topic name of the event context. String.
KEY
The key value of the event context. String.
FIELD
The property name to query. Specify one of the following values.
  • counter — The accumulated event counter value of the event context. Returns a 64-bit integer.
  • created — The time the event context was created. Returns a timestamp.
  • expire — The expiration time of the event context. Returns a timestamp.
  • timeout — The timeout time of the event context. Returns a timestamp.
  • rows — The list of rows collected in the event context. Returns an array.
  • vars — The variable map set in the event context. Returns an object.
HOST
(Optional) The hostname to which the event context belongs. If omitted, the default host is searched.

Description

The function identifies the event context using TOPIC and KEY, then returns the property value specified in FIELD.

If TOPIC or KEY is null, null is returned. If the specified event context does not exist, null is returned.

When querying expire or timeout, if that value has not been set, null is returned.

If an invalid value is specified for FIELD, an error occurs at parse time.

Error codes

Error codeDescription
invalid-evtctxget-argumentsThe number of arguments is not 3 or 4.
invalid-evtctxget-fieldThe FIELD argument cannot be evaluated.
unsupported-evtctx-fieldAn unsupported property name was specified for FIELD.

Usage examples

  1. Query the event counter per user from the login_fail topic

    evtctx topic=login_fail key=src_user max_count=5
| eval cnt = evtctxget("login_fail", src_user, "counter")

  2. Query the creation time and expiration time of an event context

    evtctx topic=login_fail key=src_user expire=300
| eval created_at = evtctxget("login_fail", src_user, "created"),
       expire_at  = evtctxget("login_fail", src_user, "expire")

  3. Query the entire variable map stored in an event context

    evtctx topic=login_fail key=src_user
| eval all_vars = evtctxget("login_fail", src_user, "vars")

  4. TOPIC is null

    evtctx topic=login_fail key=src_user
| eval cnt = evtctxget(null, src_user, "counter")
| # cnt: null

Compatibility

evtctxget() has been available since before Sonar 4.0.