Skip to content

Argus Metric Search Translator MCP Tools

These tools help the LLM express metric aggregation intent as valid Argus metric aggregation JSON before execution.

They currently support ProcessingEventsPerFilter metrics, which describe event filter processing activity across Argus detection pipelines.

General Notes

  • Use these tools when you want the LLM to prepare a valid metric aggregation request from plain-language intent.
  • ProcessingEventsPerFilter metrics cover annotation filters, analysis filters, and match filters.
  • The metric time range selects metric records by when they were submitted to the central Argus metric service.
  • If no metric time range is requested, the default range is from startOfDay to now.
  • At least one statistics.values item is required. A request with only filters and no metric values is invalid.
  • If the user asks to group, split, break down, or compare metrics by a descriptor key, the LLM can use statistics.groupBy.
  • Enum values are case-sensitive and should be kept exactly as documented.
  • If you want live Argus aggregation results after translation, the LLM can use the corresponding Metric REST MCP tool with the same aggregation intent.

Tool: generateProcessingEventsPerFilterMetricAggregationQuery

Purpose

Generate an Argus aggregation query for ProcessingEventsPerFilter metric records. The result is metric aggregation JSON that can be used to calculate totals, averages, minimums, maximums, weighted averages, or sums of squares for selected metric values.

Arguments

Field Description Type Default Required
request ProcessingEventsPerFilter metric aggregation definition the LLM builds from the request. object None Yes

request Fields

Field Description Type Default Required
filter Filters that select which metric records are included before aggregation. object Empty filter with default time range No
statistics Aggregation configuration for selected metric values, grouping, and time bucketing. Must include at least one values item. object Empty statistics request Yes
translateKey Whether descriptor key values should be translated for display where translation is available. boolean true No

request.filter Fields

Field Description Type Default Required
customer Include metric records for any of the specified customers, using customer ID or short name. array<string> None No
timeFilter Time range based on when metric records were submitted to the central Argus metric service. object { "startTime": "startOfDay", "endTime": "now" } No
keyFilter Filters for ProcessingEventsPerFilter descriptor keys, such as filter ID, filter type, host, component instance, or pipeline stage. object None No

request.filter.timeFilter Fields

Field Description Type Default Required
startTime Start of the metric submission time range. Accepts epoch millis as string, ISO-8601 UTC, or relative expressions such as startOfDay - 1 day. string startOfDay No
endTime End of the metric submission time range. Accepts epoch millis as string, ISO-8601 UTC, or relative expressions such as now. string now No

request.filter.keyFilter Fields

Field Description Type Default Required
filterID Include metrics for any of the specified event filter IDs. array<number> None No
filterType Include metrics for selected event filter types. Allowed values: AnnotationFilter, AnalysisFilter, MatchFilter. array<string> None No
componentHost Include metrics from any of the specified detection pipeline host names. array<string> None No
componentInstanceID Include metrics from any of the specified detection pipeline component instance IDs. array<number> None No
stage Include metrics from any of the specified detection pipeline stages. array<string> None No

request.statistics Fields

Field Description Type Default Required
timeBucket Time bucketing configuration based on metric submission time. Use this for requests such as per hour, per day, or one bucket for the whole range. object { "resolution": 0, "resolutionUnit": "hours" } No
groupBy Descriptor keys used to group the aggregation result. List order controls the grouping hierarchy. array<object> Empty list No
includeOthersForGroupBy Whether data excluded by group-by limits should be collected into an Others bucket. Applies only when groupBy is used. boolean true No
values Metric values to aggregate. At least one item is required. array<object> Empty list Yes

request.statistics.timeBucket Fields

Field Description Type Default Required
resolution Bucket size as a number using resolutionUnit. Use 0 to aggregate the full requested time range into one bucket. Values above 10000 are capped at 10000. number 0 No
resolutionUnit Unit for resolution. Allowed values: milliseconds, seconds, minutes, hours, days. string hours No

request.statistics.groupBy[] Fields

Field Description Type Default Required
key Descriptor key used to group the aggregation result. Allowed values: customer, filterID, filterType, componentHost, componentInstanceID, stage. string None Yes
limit Maximum number of top buckets returned for this group-by key. Accepted range: 1 to 10000; values above 10000 are capped at 10000. number 10 No

request.statistics.values[] Fields

Field Description Type Default Required
name Metric value to aggregate. Allowed values: matchTimeMS, triggerCount, triggerTimeMS. string None Yes
aggregationFunction Aggregation function to apply. Allowed values: sum, avg, min, max, wavg, sumOfSquares. string sum No
weightByValue Metric value to use as the weight when aggregationFunction is wavg. Allowed values: matchTimeMS, triggerCount, triggerTimeMS. string None Required for wavg

Metric Values

Value Meaning
matchTimeMS Time spent in milliseconds by filter logic while filtering events from the realtime stream.
triggerCount Number of events matched by the filter.
triggerTimeMS Time spent in milliseconds by trigger logic on events matched by the filter.

Usage Notes

  • Use sum for totals, avg for arithmetic averages, min and max for extremes, and wavg only when the user asks for or needs a weighted average.
  • When wavg is used, weightByValue must identify the metric value that supplies the weight.
  • resolution = 0 returns one aggregate bucket for the full selected time range unless other grouping is requested.
  • For time bucketing, choose a resolution that produces at most 10000 buckets over the selected time range.
  • Group-by limits affect which records are included in the grouped aggregation, not only how many buckets are displayed.
  • The LLM should only include filters explicitly requested by the user. It should not infer filter IDs, host names, pipeline stages, timestamps, or enum values.