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 .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:
The Micro-Agent/service settings has a defined, uniform hierarchy. The priority of the methods is as follows:
- Environment Option:
a. Single Variables - TAKIPI_APPLICATION_NAME
b. Environment String - TAKIPI_ARGS (comma separated)
- Properties file - TAKIPI_HOME\agent.properties
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:
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\
This section describes the basic OverOps Micro-Agent properties that can be configured.
The application name should represent the logical components that make up your application, for example api, app, services, etc.
Use this variable to configure the application name.
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.
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.
Set the name of the application deployment version currently running on the CLR, also see Naming your Application, Server, Deployment.
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.
The size limit (in bytes) for the temporary resources folder used by the Micro-Agent.
Enable teams to deploy a dedicated agent.properties file per application and point to a Micro-Agent. Often configured with takipi.resources.dir.
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.
The local Collector
When using a Remote Collector, introduce the Collector to the Micro-Agent. You'll need both the host and port to configure the Collector.
The local Collector
When using a Remote Collector, configure it with a passphrase to identify authorized Micro-Agents.
When using a Remote Collector, set the interval (in seconds) for the keep alive mechanism that sends a heartbeat to the Collector.
For high-availability, set the master endpoint according to which to route traffic as round-robin.
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.
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.
Allows to set the timeframe in seconds how often the statistic data is pushed to the backend.
-1 = disabled
Allows controlling the minimum log level recorded in the log view to reduce log overhead.
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.
10,000 characters (i.e. practically unlimited)
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.
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.
Sets the maximum length of a recorded string variable. This may reduce performance: lower performance for capture of longer strings.
Sets the maximum number of captured array elements. This may reduce performance: lower performance for capture of longer arrays.
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.
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.
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.one.hit.req=true or takipi.one.hit.req=1
The number of concurrent snapshots to record. Limits the maximum number of snapshots the Micro-Agent can collect simultaneously. Range: 1-5.
The period of time the Micro-Agent waits before shutting down to allow the last asynchronous messages to be sent to the Collector.
0 (not enabled)
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.
0 (no boot delay)
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.
Sets the path to the source code on the Collector host. Source code can be either in source files or JAR files.
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.
The properties in this section disable certain functions in the Micro-Agent.
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.
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.
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.
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.
Disables instrumentation and tracking of logged errors and logged warnings as events. This does not affect the log view.
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).
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
Updated 2 days ago