Instana tag filter expressions

With tag filter expression, you can specify conditions that Instana uses to selectively display or analyze data.

What are tags?

Tags in Instana can include metadata such as environment (for example, production, staging), location, application version, or any custom attributes you define.

What is a tag filter expression?

Tag filter expression specify conditions that Instana uses to selectively display or analyze data. For example, you can create a filter expression to show data that is only related to services tagged with "production" and "backend". Alternatively you can create a filter expression to monitor metrics specifically from hosts tagged with "AWS" and "us-east-1".

Tag filter expressions typically use logical operators (AND, OR) and comparison operators (equals, not equals) to combine tags and define the filtering rules effectively. Tag filter expressions are essential for focusing monitoring efforts on specific subsets of your infrastructure or applications, helping you efficiently manage and troubleshoot performance issues.

Structure of a tag filter expression in Instana

In Instana, the data model for a tag filter expression follows a structured format to define conditions based on tags that are associated with monitored entities.

Components of tag filter expressions (TFEs)

Using tag filter expressions you can filter your query with tags and logical operators such as AND and OR. You can also refine your data views by applying these expressions in the UI.

To work with TFEs, you can add the following information:

  • tagFilterExpression: Use tags and operators to filter your query. Logical operators like AND and OR can be used to combine multiple tag conditions.
  • name: The name of the tag as returned by the catalog (for example, beacon.meta or beacon.http.path).
  • value: The filter value of the tag such as:
    • STRING: Alphanumeric values. Valid operators such as EQUALS, CONTAINS, NOT_EQUAL, NOT_CONTAIN, NOT_EMPTY, IS_EMPTY.
    • NUMBER: Numerical values. Valid operators such as EQUALS, LESS_THAN, GREATER_THAN.
    • KEY_VALUE_PAIR: For meta tags like beacon.meta, you can filter by setting yourMetaTagName=foo in the value field. Valid operators such as EQUALS, CONTAINS, NOT_EQUAL, NOT_CONTAIN, NOT_EMPTY, IS_EMPTY.
  • operator: One of the valid operators for the type of the selected tag.

To get a list of all available tags, you can query the tag catalog.

Tag catalog references

To explore all available tags, you can query the following tag catalogs:

How to form a tag filter expression

  1. Tag key and value:

    • Tags are represented as key-value pairs.
    • Example: environment:production, where environment is the tag key and production is the tag value.

  2. Logical operators:

    • AND operator (&&): Combines multiple conditions where all must be true.
    • OR operator (||): Combines multiple conditions where at least one must be true.
    • NOT operator (!): Negates a condition.

  3. Comparison operators:

    • Equals (=): Matches a specific tag value.
    • Not qquals (!=): Does not match a specific tag value.
    • Exists (exists): Checks if a tag exists for an entity.

Examples of tag filter expressions

  1. Simple tag match:

    • Filter for services tagged with environment:production.
    • Expression: environment:production

  2. Multiple tags with AND operator:

    • Filter for hosts that are tagged with both environment:production and service:backend.
    • Expression: environment:production && service:backend

  3. OR operator for alternative tags:

    • Filter for services that are tagged with either environment:production or environment:staging.
    • Expression: environment:production || environment:staging

  4. Combining AND and OR:

    • Filter for services that are tagged with environment:production and either service:frontend or service:backend.
    • Expression: environment:production && (service:frontend || service:backend)

  5. Negation with NOT operator:

    • Filter for hosts not tagged with environment:development.
    • Expression: !environment:development

  6. Checking tag existence:

    • Filter for services where the version tag exists.
    • Expression: version:exists

Notes

  • Parentheses () can be used to group conditions for clarity and to specify the order of operations.
  • Instana's tag filter expressions allow for complex criteria to precisely define which monitored entities and metrics must be included or excluded from analysis or monitoring views. Adjustments can be made dynamically based on your monitoring needs and infrastructure setup.