About the .NET Micro-Agent Properties File

This document describes flags in the .NET Micro-Agent properties and the use cases where they can be used. There are two properties files: agent.properties and collector.properties to differentiate between the components. The properties are backward compatible.

The Micro-Agent properties are defined in the agent.properties file. All OverOps parameters are configurable via all two directives:

1. Environment Option:
   Add a single variable to the Environment Variables. For example:
   TAKIPI_APPLICATION_NAME=myProdApp
   Add the TAKIPI_ARGS to the Environment Variables with the arguments. For example: TAKIPI_ARGS=takipi.deployment.name=prod1.0.122,takipi.sources.path=C:\MyApp\Source
2. Properties file option: - TAKIPI_HOME\agent.properties:
   • Add an argument to the agent.properties. For example:

    takipi.deployment.name=prod1.0.122
    takipi.sources.path=C:\\MyApp\\Source

Basic Micro-Agent Features

This section describes the basic OverOps Micro-Agent properties that can be configured.

Symbols

takipi.symbols.path

To fully diagnose any error OverOps Micro-Agent uses the PDB (program database) files.
In a regular .NET process, the PDB files must be in the same folder as the EXE/DLL. If they are not in the same folder, the user must provide the PDB path to the Micro-Agent by argument.

Notes -

• ; is used as multi-parameters separator
• use double \ for any path in agent.properties file.

Naming the Application

The application name should represent the logical components that make up your application, for example api, app, services, etc.

takipi.application.name

Use this variable to configure the application name.

📘

Note

When using an IIS web application, if the application name isn't set in agent.properties, Overops will automatically detect the "application pool name" as the application name.

takipi.server.name

Configure the server and hostname on which the CLR runs when using a Collector. This is in order to differentiate it from the machine name of the Collector, which is a different machine.

In a typical monolithic web application the actual server IP or VM names are very familiar and has meaning to you, but if you are running on a kubernetes cluster and 1000s of containers running in pods and are going up and down in an highly elastic manner the IPs mean nothing. In those cases your Server Grouping should be named after logical group instances.
Example: prod-app1, prod-api1, prod-api2, prod-service1, prod-sql1, etc.

takipi.deployment.name

Set the name of the application deployment version currently running on the CLR, also see Naming your Application, Server, Deployment.

Directories

takipi.resources.dir

This folder is used when different OS users are running different Agents on the same host that may cause a conflict of permissions for the Micro-Agent under the Takipi resources directory. Permissions conflicts often cause instabilities in monitoring of applications in the UI. This parameter avoids the conflict by ensuring that each user/agent writes to its own folder.

takipi.resources.size.limit

The size limit (in bytes) for the temporary resources folder used by the Micro-Agent.

takipi.properties.file

Enable teams to deploy a dedicated agent.properties file per application and point to a Micro-Agent. Often configured with takipi.resources.dir.

Remote Collector

takipi.collector.host

When using a Remote Collector, introduce the Collector to the Micro-Agent (this is an IP address).
You'll need both the host and port to configure the Collector.

takipi.collector.port (takipi.daemon.port)

When using a Remote Collector, introduce the Collector to the Micro-Agent. You'll need both the host and port to configure the Collector.

takipi.collector.passphrase

When using a Remote Collector, configure it with a passphrase to identify authorized Micro-Agents.

takipi.collector.keepalive

When using a Remote Collector, set the interval (in seconds) for the keep alive mechanism that sends a heartbeat to the Collector.

takipi.master.endpoints

For high-availability, set the master endpoint according to which to route traffic as round-robin.

🚧

Important

The property takipi.master.endpoints should only be used in scenarios where OverOps is responsible for "load balancing" requests across collectors for two or more collectors. If you're using an external load balancer for collectors (i.e., Nginx), the takipi.collector.host and takipi.collector.port should be used to specify the load balancer.

Advanced Micro-Agent Features

Gathering Snapshots

takipi.cart.factor

Allows you to increase the amount of information collected for each snapshot. The amount of data collected during snapshot is determined by an internal algorithm called the cart.

The valid values vary between: 0.1-4 (including decimals to one decimal place). A cart factor of 2 records twice as much as a normal hit. A cart factor of 0.5 records half as much as a normal hit.

Note that larger snapshots may result in larger overhead. A larger cart factor is trading more overhead for more information. This does not affect the number of snapshots taken or levels deep into the heap.

takipi.stats.interval

Allows to set the timeframe in seconds how often the statistic data is pushed to the backend.

takipi.cerebro.min.log.level

Allows controlling the minimum log level recorded in the log view to reduce log overhead.

takipi.cerebro.message.max.length

Allows setting the maximum length of a recorded log line in the log view. Any log message recorded for the log view is trimmed to avoid exceeding this limitation.

takipi.max.depth

Configures how deep into the heap to let the Micro-Agent to capture variables. This may accelerate reaching the cart limit, resulting in displaying less data in other methods in a snapshot.

takipi.max.stack.depth

Sets the maximum number of frames collected in a snapshot. Moves from top (location of exception) to bottom (near thread run). The limitation includes 3rd-party (blacklisted) frames.

takipi.max.string.length

Sets the maximum length of a recorded string variable. This may reduce performance: lower performance for capture of longer strings.

takipi.max.array.length

Sets the maximum number of captured array elements. This may reduce performance: lower performance for capture of longer arrays.

takipi.max.string.encoding.size

Limits the size of the string that the Micro-Agent captures. This means that the Micro-Agent captures only the prefix of strings that are longer than this parameter.

takipi.max.array.encoding.size

Limits the size of the array that the Micro-Agent captures. This means that the Micro-Agent captures only the prefix of arrays that are longer than this parameter.

takipi.one.hit.req

The Agent only evacuates one snapshot per event for the entire lifetime of the CLR. This property can help reduce overhead when having one snapshot is enough.

takipi.concurrency.level

The number of concurrent snapshots to record. Limits the maximum number of snapshots the Micro-Agent can collect simultaneously. Range: 1-5.

takipi.shutdown.gracetime

The period of time the Micro-Agent waits before shutting down to allow the last asynchronous messages to be sent to the Collector.

Optimization Features

Advanced Optimization

takipi.boot.time

Configures a time frame during CLR startup in which the Micro-Agent does not collect any information (snapshots or statistics) or perform any instrumentation. This increases boot times slowed down by the OverOps Micro-Agent.

takipi.disable.exception.handling.time

Configures a time frame during CLR startup in which the Micro-Agent does not collect any information (snapshots or statistics) or perform any instrumentation. Callback is triggered, but OverOps will return immediately on every call. This increases boot times slowed down by the OverOps Micro-Agent.

Source Attach

takipi.sources.path

Sets the path to the source code folder on the Collector host.
The argument is provided to the agent, but the sources must reside in the collector machine.

Notes -

• ; is used as multi-parameters separator
• use double \ for any path in agent.properties file.

takipi.remote.sources.dir

This parameter is used in Hybrid mode only.
Set the path to the source code on a remote Storage Server. The path is relative to the Storage mount point.

Micro-Agent Feature Flags

The properties in this section disable certain functions in the Micro-Agent.

takipi.no.recursive.context

In certain applications, some methods are repeatedly called in the same call stack. This causes significant CPU overhead. This flag disables instrumenting a method multiple times per call stack.

takipi.no.locals

Excludes the variable state from the snapshots, to reduce overhead for diagnostics purposes. This flag turns off the Micro-Agent’s CLR TI's (Tool Interface) capability to extract local variable data during snapshot encoding causing significant overhead.

takipi.no.ex.callback

Turns off Micro-Agent registration to the CLR TI exception callback, that causes severe overhead in the CLR. When set, no exceptions are displayed. For diagnostics purposes.

takipi.no.ex

Turns off Micro-Agent CLR exception callback capability that causes severe overhead in the CLR. When set, callback is triggered but returned immediately. For diagnostics purposes.

takipi.no.xmen

Disables instrumentation and tracking of logged errors and logged warnings as events. This does not affect the log view.

takipi.no.rich.hits

Rich hits are snapshots that contain significantly more data than standard snapshots. Encoding rich hits increases overhead, that this flag turns off. Disabling rich hits has a similar effect to supplying a ‘cart factor’ argument (see above).

takipi.no.tlpk

Disables beautification of thread-local MDC recording. When recording thread-local data during snapshots, OverOps extracts logger MDC data surgically and makes it presentable for the user in the UI. Disabling takipi.no.tlpk keeps recording all thread-local data, but MDC information is buried within other TLS data.

takipi.no.cerebro

Disables log statement capture for the log view. It potentially provides significant performance benefits. Log capture can affect Garbage Collection when logs are dense. This does not affect recording of logged errors and logged warnings as events.

takipi.no.req.inv

Disables instrumentation and collection of event statistics. Snapshots are still taken, but the Dashboard will not have any statistics for events, nor will statistics be sent to StatsD.

takipi.no.overmind

Disables instrumentation and collection of CLR view information.

takipi.no.contexts

Disables instrumentation and collection of entry point information. When this flag is disabled, the Entry Points column on the Dashboard only displays the method which threw the event.

takipi.no.xtl

Disables injection of log links into log statements.This does not affect the collection of logged warnings/errors as events, or the injection of log links into throwable messages.

takipi.no.memento

Disables displaying log links for all events, even when no specific snapshot was taken for that instance, and the log link points to the most recent snapshot available.

Micro-Agent Verbose Logging

takipi.log.to.console

This flag makes the Micro-Agent write its internal log messages to the standard output instead of to the bugtale_agent.XXXX.log file.

The flag adds verbose debugging to all logs whenever turned on as long as the server is on; to stop, you'll, need to restart the service without the flag (it is recommended to use this flag for a limited time to figure out problems).

takipi.log.file

When using Remote Collector, the default Micro-Agent log is written in the folder. This solves communication issues between the Micro-Agent and the Remote Collector. The log file must be in an existing path.

takipi.silent

Prints debug log statements to the standard output. When false, upon the first event captured, the Micro-Agent prints sanity log statements and a log link to an event.

takipi.dn.permit.app.pools

Enable the agent attach only for the named application pool.

takipi.dn.banned.app.pools

Disable the agent attach for the named application pool.

takipi.etl

This parameter enables instrumentation and injection of log links into throwable messages. This does not affect the injection of log links into logging statements. Currently, exception tiny links are disabled by default and this flag is required to turn them on.

Dormant Triggers

dormant

Creating a dormant file in the Micro-Agent resources folder, causes it to shut down at runtime. The shutdown is visible in the Micro-Agent log. You'll need to restart the CLR to return to normal operations.

dormant.slow

Creating a dormant.slow file in the Micro-Agent resources folder, induces a gradual shutdown over the course of 20 minutes. Mechanisms are shut down separately, constantly updating the Micro-Agent log on feature shutdown and diagnostics. You'll need to restart the CLR to return to normal operations.

Entrypoint customization

The following table describes the agent properties / environment variables that are used for defining prioritized / deprioritized entrypoints. Read more Entry Point Customization

Notes -

• Class / Namespaces names are case sensitive
• : is used as multi-parameters separator
• both . and / can be used as namespace/class delimiter

Usage examples -

1. takipi.prioritized.classes=MyNamespace.MyClassA:MyNamespace/MyClassB (usage example for multi parameters and different delimiters)
2. takipi.prioritized.packages=com.company:MyNamespace (usage example for multi parameters)
3. takipi.deprioritized.classes=MyNamespace/MyClassA