In large applications, instrumentation can lead to performance hits and can affect costs. This may have become a greater consideration when IBM introduced the data-ingest-based Fair Use Policy (FUP) for Instana. Under FUP, clients are entitled to a fair use limit and additional on-demand data ingest for exceptional needs. Instana has also been rolling out better support for optimizing data ingestion, including but not limited to:
- Disabling tracing by technology
- Endpoint filtering
- Span attributes-based filtering
In this post, we will check out the recent support of these features in the Instana PHP Tracer and look at how to configure them.
Span disabling
The span disabling feature can be used to disable the instrumentation of certain technologies through a YAML configuration. This configuration can be added to the com.instana.tracing key in the common Instana agent configuration.yaml file or in a custom configuration file with its path in the environment variable INSTANA_CONFIG_PATH passed to PHP. Although PHP needs to be restarted the first time this configuration is added, later changes to the configuration will be applied in real time without interference.
The syntax and configuration details can be found in the Instana PHP Tracing Documentation.
Span disabling example #1
We have a webpage that creates many internal calls for the Wordpress framework and logs a warning message. The trace of the PHP script for the webpage is as follows:
Let's disable tracing for these framework and logging calls. The following is added to the agent configuration.yaml file:
com.instana.tracing:
disable:
- frameworks: true # Disables instrumentation of web application frameworks
- logging: true # Disables instrumentation of logging frameworks
Opening the webpage now generates the following trace:
Span disabling example #2
We have a webpage that makes database calls other than the MySQL calls that we are interested in tracing. The trace is as follows:
Let's disable tracing for all databases other than MySQL. The following is written to the /etc/instana/config.yaml file:
tracing:
disable:
- databases: true # Disables database instrumentation
- mysql: false # Keeps MySQL instrumentation
Then, the environment variable INSTANA_CONFIG_PATH=/etc/instana/config.yaml is set and PHP is restarted once. The new trace is as follows:
Span filtering
The span filtering feature can be used to exclude spans from traces with finer control. It can also be used for HTTP endpoint filtering by specifying HTTP span attributes. Like span disabling, it can be configured in the common Instana agent configuration.yaml or in a custom configuration file and can work alongside span disabling. As with span disabling, changes in the configuration will be applied in real-time as long as the file is present when PHP is started.
Filtering is configured through a list of exclude and include rules, with include rules taking precedence. See the Instana PHP Tracing Documentation for syntax and configuration details.
Span filtering example #1
There is a webpage that queries a temporary database. We don't want to waste ingest capacity on it. The trace looks like this:
Let's filter out only MySQL calls on the tempdb database. The following is added to the agent configuration.yaml file:
com.instana.tracing:
filter:
exclude:
- name: exclude MySQL calls for tempdb
attributes:
- key: mysqli.dsn # condition on MySQL data source name (DSN)
values: [dbname=tempdb] # value in DSN when database name is tempdb
match_type: contains # DSN string matches if it contains the value
We restart PHP once and reload the webpage. The trace is now as follows:
Span filtering example #2
There is a webpage that checks the health of the HTTP endpoint of an API multiple times before querying it for content. The trace is as follows:
Let's have the tracer exclude all HTTP calls from the trace and keep only the /api/items endpoint in the trace. The following is written to the /etc/instana/config.yaml file:
tracing:
filter:
exclude:
- name: exclude HTTP calls
attributes:
- key: category # A condition on span category
values: [http] # Match any span of the HTTP category
include:
- name: include HTTP endpoint /api/items
attributes:
- key: http.url # A span attribute condition on HTTP URL
values: [/api/items] # The suffix of the URL we want to keep
match_type: endswith # URL matches if it ends with the suffix
Since include rules take precedence, a call to the /api/items endpoint will still be included despite the call also satisfying the exclude rule that we have. The environment variable INSTANA_CONFIG_PATH=/etc/instana/config.yaml is set, and PHP is restarted. The trace now looks as follows:
Conclusion
Instana's span disabling and span filtering features, which are implemented by tracers such as the PHP tracer, can be used to reduce data ingestion in instrumented applications. This is especially true for large applications looking to adapt to FUP. This post has demonstrated how to enable span disabling and filtering effectively for the Instana PHP Tracer.
See also
#Tracing