doc.overops.com

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

Important

The .NET Micro-Agent can be currently used for pre-production environments only.

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

Environment Variable
Properties File

Examples:

TAKIPI_APPLICATION_NAME

takipi.application.name

The Micro-Agent/service settings has a defined, uniform hierarchy. The priority of the methods is as follows:

  1. Environment Option:
    a. Single Variables - TAKIPI_APPLICATION_NAME
    b. Environment String - TAKIPI_ARGS (comma separated)
  2. Properties file - TAKIPI_HOME\agent.properties

Setting up Takipi Arguments

To add arguments to the Micro-Agent:

  • Use the System Properties, add the TAKIPI_ARGS to the Environment Variables.
  • Use the agent.properties file located under Takipi install folder to add arguments. For example:

TAKIPI_ARGS=takipi.deployment.name=prod1.0.122,takipi.sources.path=C:\WingtipToysSource

Mandatory Takipi Arguments

To fully diagnose any error, the TAKIPI_ARGS/agent.properties must include the following properties:

  • takipi.symbols.path (PDB) - In a regular .NET process, the PDB (program database) 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.

When using IIS to analyze the web application, this argument must be added to TAKIPI_ARGS, for example: takipi.symbols.path=C:\Users\DotNetOverOpsVm\Desktop\WingToysPublish\bin.

  • takipi.sources.path (Source code) - Indicates the path of the sources in the Collector machine. The sources should reside in the collector machine, for example: takipi.sources.path=C:\Users\DotNetOverOpsVm\Desktop\WingToysPublish_6_7_18_2\sources\

Basic Micro-Agent Features

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

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 Variable
Properties File
Example

TAKIPI_APPLICATION_NAME

takipi.application.name

takipi.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 Variable
Properties File

TAKIPI_SERVER_NAME

takipi.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 Variable
Properties File

TAKIPI_DEPLOYMENT_NAME

takipi.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 Variable
Properties File
Default

TAKIPI_RESOURCES_DIR

takipi.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 Variable
Properties File
Example
Default

TAKIPI_RESOURCES_SIZE_LIMIT

takipi.resources.size.limit

takipi.resources.size.limit=52428800

Unlimited

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 Variable
Properties File
Example
Default

TAKIPI_PROPERTIES_FILE

takipi.properties.file

takipi.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 Variable
Properties File
Example
Default

TAKIPI_COLLECTOR_HOST

takipi.collector.host

takipi.collector.host=10.121.0.11

The 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 Variable
Properties File
Example
Default

TAKIPI_COLLECTOR_PORT

takipi.collector.port

takipi.collector.port=6060

The local Collector

takipi.collector.passphrase

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

Environment Variable
Properties File
Example
Default

TAKIPI_COLLECTOR_PASSPHRASE

takipi.collector.passphrase

takipi.collector.passphrase=SECRET

empty

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 Variable
Properties File
Example
Default

TAKIPI_COLLECTOR_KEEPALIVE

takipi.collector.keepalive

takipi.keep.alive=10

0

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 Variable
Properties File
Example
Default

TAKIPI_MASTER_ENDPOINTS

takipi.master.endpoints

takipi.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 Variable
Properties File
Example
Default

TAKIPI_CART_FACTOR

takipi.cart.factor

takipi.cart.factor=0.5

1

takipi.stats.interval

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

Environment Variable
Properties File
Example
Default

TAKIPI_STATS_INTERVAL

takipi.stats.interval

takipi.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 Variable
Properties File
Example
Possible Values
Default

TAKIPI_CEREBRO_MIN_LOG_LEVEL

takipi.cerebro.min.log.level

takipi.cerebro.min.log.level=LOG_LEVEL_INFO

LOG_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 Variable
Properties File
Example
Default

TAKIPI_CEREBRO_MESSAGE_MAX_LENGTH

takipi.cerebro.message.max.length

takipi.cerebro.message.max.length=2000

10,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 File
Example
Default

TAKIPI_MAX_DEPTH

takipi.max.depth

takipi.max.depth=10

5

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 Variable
Properties File
Example
Default

TAKIPI_MAX_DEPTH

takipi.max.stack.depth

takipi.max.stack.depth=500

2000

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 Variable
Properties File
Example
Default

TAKIPI_MAX_STRING_LENGTH

takipi.max.string.length

takipi.max.string.length=400

300

takipi.max.array.length

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

Environment Variable
Properties File
Example
Default

TAKIPI_MAX_ARRAY_LENGTH

takipi.max.array.length

takipi.max.array.length=50

25

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 Variable
Properties File
Example
Default

TAKIPI_MAX_STRING_ENCODING_SIZE

takipi.max.string.encoding.size

takipi.max.string.encoding.size=2000

300

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 Variable
Properties File
Example
Default

TAKIPI_MAX_ARRAY_ENCODING_SIZE

takipi.max.array.encoding.size

takipi.max.array.encoding.size=50

25

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 Variable
Properties File
Example
Default

TAKIPI_ONE_HIT_REQ

takipi.one.hit.req

takipi.one.hit.req=true or takipi.one.hit.req=1

false

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 Variable
Properties File
Example
Default

TAKIPI_CONCURRENCY_LEVEL

takipi.concurrency.level

takipi.concurrency.level=3

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.

Environment Variable
Properties File
Example
Default

TAKIPI_SHUTDOWN_GRACETIME

takipi.shutdown.gracetime

takipi.shutdown.gracetime=3000

0 (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 Variable
Properties File
Example
Default

TAKIPI_BOOT_TIME

takipi.boot.time

takipi.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 Variable
Properties File
Example
Default

TAKIPI_DISABLE_EXCEPTION_HANDLING_TIME

takipi.disable.exception.handling.time

takipi.disable.exception.handling.time=10m

0

Source Attach

takipi.sources.path

Sets the path to the source code on the Collector host. Source code can be either in source files or JAR files.

Environment Variable
Properties File
Example
Default

TAKIPI_SOURCES_PATH

takipi.sources.path

takipi.sources.path=/home/user/src/….

-

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 Variable
Properties File

TAKIPI_NO_RECURSIVE_CONTEXT

takipi.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 Variable
Properties File

TAKIPI_NO_LOCALS

takipi.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 Variable
Properties File

TAKIPI_NO_EX_CALLBACK

takipi.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 Variable
Properties File

TAKIPI_NO_EX

takipi.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 Variable
Properties File

TAKIPI_NO_XMEN

takipi.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 Variable
Properties File

TAKIPI_NO_RICH_HITS

takipi.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 Variable
Properties File

TAKIPI_NO_TLPKY

takipi.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 Variable
Properties File

TAKIPI_NO_CEREBRO

takipi.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 Variable
Properties File

TAKIPI_NO_REQ_INV

takipi.no.req.inv

takipi.no.overmind

Disables instrumentation and collection of CLR view information.

Environment Variable
Properties File

TAKIPIN_NO_OVERMIND

takipi.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 Variable
Properties File

TAKIPI_NO_CONTEXTS

takipi.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 Variable
Properties File

TAKIPI_NO_XTL

takipi.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 Variable
Properties File

TAKIPI_NO_MEMENTO

takipi.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 Variable
Properties File

TAKIPI_LOG_TO_CONSOLE

takipi.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 Variable
Properties File
Example

TAKIPI_LOG_FILE

takipi.log.file

takipi.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 Variable
Properties File
Example
Default

TAKIPI_SILENT

takipi.silent

takipi.silent=false

True

takipi.dn.permit.app.pools

Enable the agent attach only for the named application pool.

Properties File
Example

takipi.dn.permit.app.pools

takipi.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 File
Example

takipi.dn.banned.app.pools

takipi.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 Variable
Properties File
Example

TAKIPI_ETL

takipi.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
Property
Environment variable

takipi.prioritized.classes

TAKIPI_PRIORITIZED_CLASSES

takipi.prioritized.packages

TAKIPI_PRIORITIZED_PACKAGES

takipi.deprioritized.classes

TAKIPI_DEPRIORITIZED_CLASSES

takipi.deprioritized.packages

TAKIPI_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

Updated 3 months ago

.NET Agent Properties


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.