.NET Agent Properties

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:

Environment VariableProperties File
Examples:TAKIPI_APPLICATION_NAMEtakipi.application.name
  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.
Environment VariableProperties FileExample
TAKIPI_SYMBOLS_PATHtakipi.symbols.pathtakipi.symbols.path=C:\Source1;C:\Source2

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.

Environment VariableProperties FileExample
TAKIPI_APPLICATION_NAMEtakipi.application.nametakipi.application.name=OverOps

📘

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.

Environment VariableProperties File
TAKIPI_SERVER_NAMEtakipi.server.name

takipi.deployment.name

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

Environment VariableProperties File
TAKIPI_DEPLOYMENT_NAMEtakipi.deployment.name

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.

Environment VariableProperties FileDefault
TAKIPI_RESOURCES_DIRtakipi.resources.dir<TAKIPI_INSTALL_DIRECTORY>/resources

takipi.resources.size.limit

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

Environment VariableProperties FileExampleDefault
TAKIPI_RESOURCES_SIZE_LIMITtakipi.resources.size.limittakipi.resources.size.limit=52428800Unlimited

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.

Environment VariableProperties FileExampleDefault
TAKIPI_PROPERTIES_FILEtakipi.properties.filetakipi.properties.file=/home/user/software/takipi/app1.properties./agent.properties

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.

Environment VariableProperties FileExampleDefault
TAKIPI_COLLECTOR_HOSTtakipi.collector.hosttakipi.collector.host=10.121.0.11The local 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.

Environment VariableProperties FileExampleDefault
TAKIPI_COLLECTOR_PORTtakipi.collector.porttakipi.collector.port=6060The local Collector

takipi.collector.passphrase

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

Environment VariableProperties FileExampleDefault
TAKIPI_COLLECTOR_PASSPHRASEtakipi.collector.passphrasetakipi.collector.passphrase=SECRETempty

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.

Environment VariableProperties FileExampleDefault
TAKIPI_COLLECTOR_KEEPALIVEtakipi.collector.keepalivetakipi.keep.alive=100

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.

Environment VariableProperties FileExampleDefault
TAKIPI_MASTER_ENDPOINTStakipi.master.endpointstakipi.master.endpoints=52.91.252.195:6060,54.196.19.7:6060,54.172.19.220:6060

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.

Environment VariableProperties FileExampleDefault
TAKIPI_CART_FACTORtakipi.cart.factortakipi.cart.factor=0.51

takipi.stats.interval

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

Environment VariableProperties FileExampleDefault
TAKIPI_STATS_INTERVALtakipi.stats.intervaltakipi.stats.interval=20-1 = disabled

takipi.cerebro.min.log.level

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

Environment VariableProperties FileExamplePossible ValuesDefault
TAKIPI_CEREBRO_MIN_LOG_LEVELtakipi.cerebro.min.log.leveltakipi.cerebro.min.log.level=LOG_LEVEL_INFOLOG_LEVEL_TRACE
LOG_LEVEL_DEBUG
LOG_LEVEL_INFO
LOG_LEVEL_WARN
LOG_LEVEL_ERROR
LOG_LEVEL_TRACE

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.

Environment VariableProperties FileExampleDefault
TAKIPI_CEREBRO_MESSAGE_MAX_LENGTHtakipi.cerebro.message.max.lengthtakipi.cerebro.message.max.length=200010,000 characters (i.e. practically unlimited)

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.

Properties FileExampleDefault
TAKIPI_MAX_DEPTHtakipi.max.depthtakipi.max.depth=105

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.

Environment VariableProperties FileExampleDefault
TAKIPI_MAX_DEPTHtakipi.max.stack.depthtakipi.max.stack.depth=5002000

takipi.max.string.length

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

Environment VariableProperties FileExampleDefault
TAKIPI_MAX_STRING_LENGTHtakipi.max.string.lengthtakipi.max.string.length=400300

takipi.max.array.length

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

Environment VariableProperties FileExampleDefault
TAKIPI_MAX_ARRAY_LENGTHtakipi.max.array.lengthtakipi.max.array.length=5025

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.

Environment VariableProperties FileExampleDefault
TAKIPI_MAX_STRING_ENCODING_SIZEtakipi.max.string.encoding.sizetakipi.max.string.encoding.size=2000300

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.

Environment VariableProperties FileExampleDefault
TAKIPI_MAX_ARRAY_ENCODING_SIZEtakipi.max.array.encoding.sizetakipi.max.array.encoding.size=5025

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.

Environment VariableProperties FileExampleDefault
TAKIPI_ONE_HIT_REQtakipi.one.hit.reqtakipi.one.hit.req=true or takipi.one.hit.req=1false

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.

Environment VariableProperties FileExampleDefault
TAKIPI_CONCURRENCY_LEVELtakipi.concurrency.leveltakipi.concurrency.level=35

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.

Environment VariableProperties FileExampleDefault
TAKIPI_SHUTDOWN_GRACETIMEtakipi.shutdown.gracetimetakipi.shutdown.gracetime=30000 (not enabled)

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.

Environment VariableProperties FileExampleDefault
TAKIPI_BOOT_TIMEtakipi.boot.timetakipi.boot.time=10m
takipi.boot.time=100s
0 (no boot delay)

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.

Environment VariableProperties FileExampleDefault
TAKIPI_DISABLE_EXCEPTION_HANDLING_TIMEtakipi.disable.exception.handling.timetakipi.disable.exception.handling.time=10m0

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.

Environment Variable

Properties File

Example

Default

TAKIPI_SOURCES_PATH

takipi.sources.path

takipi.sources.path=C:/user/src;C:\user\src2

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.

Environment Variable

Properties File

Example

Default

TAKIPI_REMOTE_SOURCES_DIR

takipi.remote.sources.dir

takipi.remote.sources.path=/sources/v1

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.

Environment VariableProperties File
TAKIPI_NO_RECURSIVE_CONTEXTtakipi.no.recursive.context

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.

Environment VariableProperties File
TAKIPI_NO_LOCALStakipi.no.locals

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.

Environment VariableProperties File
TAKIPI_NO_EX_CALLBACKtakipi.no.ex.callback

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.

Environment VariableProperties File
TAKIPI_NO_EXtakipi.no.ex

takipi.no.xmen

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

Environment VariableProperties File
TAKIPI_NO_XMENtakipi.no.xmen

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).

Environment VariableProperties File
TAKIPI_NO_RICH_HITStakipi.no.rich.hits

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.

Environment VariableProperties File
TAKIPI_NO_TLPKYtakipi.no.tlpky

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.

Environment VariableProperties File
TAKIPI_NO_CEREBROtakipi.no.cerebro

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.

Environment VariableProperties File
TAKIPI_NO_REQ_INVtakipi.no.req.inv

takipi.no.overmind

Disables instrumentation and collection of CLR view information.

Environment VariableProperties File
TAKIPIN_NO_OVERMINDtakipi.no.overmind

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.

Environment VariableProperties File
TAKIPI_NO_CONTEXTStakipi.no.contexts

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.

Environment VariableProperties File
TAKIPI_NO_XTLtakipi.no.xtl

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.

Environment VariableProperties File
TAKIPI_NO_MEMENTOtakipi.no.memento

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).

Environment VariableProperties File
TAKIPI_LOG_TO_CONSOLEtakipi.log.to.console

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.

Environment VariableProperties FileExample
TAKIPI_LOG_FILEtakipi.log.filetakipi.log.file=<path/to/file.log>

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.

Environment VariableProperties FileExampleDefault
TAKIPI_SILENTtakipi.silenttakipi.silent=falseTrue

takipi.dn.permit.app.pools

Enable the agent attach only for the named application pool.

Properties FileExample
takipi.dn.permit.app.poolstakipi.dn.permit.app.pools=app_pool_name_goes_in_here, second_once_goes_here

takipi.dn.banned.app.pools

Disable the agent attach for the named application pool.

Properties FileExample
takipi.dn.banned.app.poolstakipi.dn.banned.app.pools=app_pool_name_goes_in_here,second_once_goes_here

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.

Environment VariableProperties FileExample
TAKIPI_ETLtakipi.etl=1 - or- takipi.etl=true

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
PropertyEnvironment variable
takipi.prioritized.classesTAKIPI_PRIORITIZED_CLASSES
takipi.prioritized.packagesTAKIPI_PRIORITIZED_PACKAGES
takipi.deprioritized.classesTAKIPI_DEPRIORITIZED_CLASSES
takipi.deprioritized.packagesTAKIPI_DEPRIORITIZED_PACKAGES

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