Filtering with Dynamic Focus

The Instana Dynamic Focus search bar is displayed on the Infrastructure Map page, and it is used for specifying the scope for events and alerts.

Dynamic Focus is a robust search and filter function that can search through all the data contexts simultaneously. Microservice architecture uses a complex variety of data contexts that are all clustered together. By using Dynamic Focus, you can filter across the data contexts to have a strong system-wide understanding.

Dynamic Focus enables the following kinds of queries, for example:

  • Filter infrastructure
    • with open issues
    • of a specific technology
    • for a specific service and change event
  • Filter events
    • for a specific service and infrastructure combination
    • on a specific container and technology
    • on specific infrastructure

Dynamic Focus takes advantage of the following capabilities:

  • Dynamic Graph – A cohesive model that Instana uses, which contains physical and logical components with all historical attributes and metrics. The Dynamic Graph also includes distributed traces and events. All nodes in the graph are connected based on their dependencies. The various views in Instana visualize the data of the graph, and Dynamic Focus filters the graph to provide specific subviews and focus.

  • Auto Discovery – The Instana agent automatically discovers all components and their dependencies that are held in the graph in real-time. Any saved filter adapts to the current situation of your systems and applications without any manual change or configuration.

  • Incidents – Instana incidents are based on KPIs and machine learning and provide condensed information about an incident. The information includes the dependencies to services, traces, and physical components, and they can be used by Dynamic Focus to filter only the components that are part of a particular incident.

Focusing on application components

The following example helps you to understand the concept of Dynamic Focus. Consider the graph representation of a zoned application that is running on two hosts with four containers each. A Java virtual machine (JVM) is running in every container, and each of the two hosts runs two Tomcats and two Elasticsearch instances, which provide a service per host. A simplified version of the Dynamic Graph model looks like the following diagram:

The filtering capability reduces the nodes in the graph based on a search query.

A query for entity.type:tomcat matches all the Tomcat instances in the graph. This means that containers with Elasticsearch entities and the corresponding services no longer are visible when you view your infrastructure, application, and traces in the standard views.

Any chart, change, issue, or incident in Instana can be seen only in the context of the reduced graph.

Another example query is to search for all JVMs 1.8, such as entity.jvm.version:1.8.*

In this case, the graph looks as shown:

Dynamic Focus is a powerful tool to find and focus user attention on single entities, or groups of entities, within the graph that match certain criteria.

Focusing on management attributes

Instana also has structures that are outside the Dynamic Graph, but refer to the Dynamic Graph, such as events (like a change), issues, or incidents. An incident might contain services where Instana found KPI outliers and might contain entities with issues like high CPU load.

By using the search capability of Dynamic Focus, you can query and filter for incidents like event.state:open event.type:incident. The search filters all the active incidents in the currently selected timeframe. In this example, it is assumed that only one active incident is available when a degradation of an Elasticsearch service causes subsequent degradation of a Tomcat service.

Because the incident that matches has references to the two services, the query filters only the relevant entities.

If you search for a service, then only the incidents that contain this service are shown.

Lucene query syntax

Instana uses Lucene query syntax to build complex queries from the terms that are mapped to the application components and Boolean operators. A robust variety of query types are supported, like free text searches, tag filtering, CPU count queries, and more. The search bar aides the user in building queries by automatically highlighting valid individual terms from the rest of the string. In addition, you can avoid common string syntax pitfalls, such as confusing the free text query and with the Boolean operator AND.

The form that Lucene queries take varies depending on the implementation. In Instana, all queries proceed from a field to a field modifier and then to a quantifier. Both field values are separated by a period, while the quantifier is set off by a colon. For example, if you want to filter all the Tomcat instances in your application, then use the query entity.type: tomcat in the search bar. Instana removes everything from view except for all entities of the type labeled "tomcat."

The entity.type:tomcat query is just one query phrase. To build flexible and complex filters that show you exactly what you need, string different query phrases together with Boolean operators, such as AND, OR, and NOT. See the following example:

Default operator

The AND operator is the default conjunction operator. So, if no Boolean operator is used between two terms, the AND operator is used.

For example, entity.type:tomcat event.state:open is equivalent to entity.type:tomcat AND event.state:open. Using of the AND operator when no Boolean operator is used, diverges from the Lucene standard, which uses OR by default.

Complex subqueries

Lucene query syntax and Dynamic Focus queries do not support complex Boolean terms.

Especially, the negation of subqueries doesn't work as expected in the Dynamic Focus query. The following query does not yield the expected results:

entity.kubernetes.namespace:my-namespace AND NOT (entity.kubernetes.pod.name:my-name AND event.text:"ContainersNotReady")

The query is processed in a way that the terms in the subquery inside the parentheses are not associated to each other when Boolean logic is applied. The following query is processed:

entity.kubernetes.namespace:my-namespace AND NOT entity.kubernetes.pod.name:my-name AND NOT event.text:"ContainersNotReady"

Auto-complete

The Dynamic Focus search bar supports autocompletion for search fields and highlights the Lucene query terms while you type. While typing the query terms, the search bar proposes search fields that match the current input. If you do not have a command of Lucene syntax, then you can get automatic help. All query proposals that appear in a drop-down list as follows the search bar. If the needed proposal is in view, click or go to it by using the arrow keys.

Instana's search function is zero-time, which means that the results appear when you enter your search criteria. You can also save, edit, and delete filters to speed up your workflow.

Known limitations

Syntax constraints

  • White space is not allowed between the ! and the query to be negated. Use !<query> or NOT <query> instead.
  • When multiple of the same entity.application.name, entity.service.name, entity.endpoint.name Dynamic Focus keywords are used together, they can be joined only by the OR operator. For example, the queries entity.application.name:foo AND entity.application.name:bar and entity.application.name:foo entity.application.name:bar are not supported. The query entity.application.name:foo OR entity.application.name:bar is supported.
  • When multiple of different entity.application.name, entity.service.name, entity.endpoint.name Dynamic Focus keywords are used together, they can be joined only by the AND operator. For example, the query entity.application.name:foo OR entity.service.name:bar is not supported, whereas the query entity.application.name:foo AND entity.service.name:bar is supported.
  • The queries that contain a negation of the application, service, or endpoint name are not supported. Therefore, NOT entity.application.name:foo, !entity.service.name:bar, and NOT entity.endpoint.name:foobar are invalid. However, you can filter out events of an application, service, or endpoint by using NOT event.entity.label:foo instead.
  • The Dynamic Focus queries entity.application.name:<term>, entity.service.name:<term>, and entity.endpoint.name:<term> are evaluated by using the string contains logic. For example, the Dynamic Focus query entity.application.name:shop also matches entity.application.name:shop-frontend.
  • The Dynamic Focus query keywords entity.application.name, entity.service.name, and entity.endpoint.name are supported only in Boolean queries (see Boolean logic constraints), term queries, phrase queries, and prefix queries.

Query limitations

  • Dynamic Focus queries on event.text that contains hyphens might return unexpected results. For example, the event.text:"foo-bar-random" query returns the events that contain just foo,bar or random due to tokenization of the Lucene analyzer.
  • When you search with most Kubernetes keywords, you can't select Host or Availability Zone type entities. As an example, the entity.kubernetes.deployment.name:my-K8s-deployment AND entity.selfType:host query does not return any host. In contrast, the entity.kubernetes.deployment.name:my-K8s-deployment AND entity.selfType:docker query returns all Docker containers that are related to the deployment. However, you can use a few Kubernetes keywords entity.kubernetes.cluster.* and entity.kubernetes.node.* to select Host entities. For example, to return all the related hosts of the cluster, use the entity.kubernetes.cluster.label:my-K8s-cluster AND entity.selfType:host query.

FAQ

Using wildcard (*) inside double quotation marks ("") does not yield expected results.

No matches are returned because the * symbol is evaluated as a character and not as a wildcard in this case. According to the Lucene specification, single and multiple character wildcard searches in phrase queries are not supported. A phrase query is a group of words that are surrounded by double quotation marks, such as event.text:"something bad happened".

I am getting search result counts, which seem inconsistent.

Sometimes, the result counts might be confusing. For instance, when you search within the Infrastructure map, the searches within the views can match more entities than that are visible within the views, such as services, which are not visible in the Infrastructure map.

What fields are searched when I do not specify any fields in the search query?

When you don't specify any fields in a search query, Dynamic Focus targets the current context to provide meaningful results. This means that it searches the entity fields when you are on the infrastructure map view and searches event data when you are on the event view.

What is the difference between entity.selfType and entity.type?

Searching with entity.selfType limits the search results to the entity that is searched for. Searching with entity.type includes all the children of the entity that is searched for. For example, when you search with entity.selfType:host, the Infrastructure map shows only the host entities and all parent entities, like the zone. But when you search with entity.type:host, the search results include what is running on the host, such as webservers and databases. However, both entity.type and entity.selfType yield the same results for entity types of the application perspectives. For example, when you use the entity.type:endpoint query in the events view, the list contains only the events that are detected on endpoint entities.