Discussion Feed

Workbench is an inbuilt feature provided with each extension to help you to fine-tune the extension setup before you actually deploy it on the Controller. Workbench functionality is inbuilt with each extension JAR file.   Currently, the AppDynamics Platform does not allow a user to delete a metric once it has been registered. As soon as you deploy an extension directly after downloading, it will have several default settings.   If you wanted to make a minor change, say in the metricPrefix of the extension, after you deployed it with the default configuration, the platform would not allow you to delete the metrics with the default metricPrefix and you would have to keep the old metrics as well.   This useful feature should be used during the process of deploying each extension, since it will give you a better idea of what metrics will be recorded. If you see that you are missing some metrics, this tool will give you an opportunity to add those metrics as well.   In order to use Extensions Workbench, follow these steps:   Download the extension ZIP file from Cisco DevNet and place it in the monitors folder. Extract the zip file. In the terminal, navigate to the extension folder. Verify that you have the main extension JAR file. Navigate to the extension folder that contains the jar file and execute the following command to start Workbench mode: java -jar cassandra-monitoring-extension.jar Note: Workbench by default uses port 9090. If you would like to change that to another port,  use the following structure to build your command:  java -jar <extension-jar> <host> <port> If you see the following output in the terminal, this means that it worked correctly and you have officially started Workbench Mode. Now, open your browser and navigate to  http://localhost:9090/ . This starts the HTTP server that allows you to access the Workbench Mode. Verify that all the desired metrics are present.  Remove any unwanted metrics from the config.yml file to reduce noise. As you explore the map of metrics, you can see if you are getting a valid output on the graph on right. The metrics that are listed in the config.yml are the ones that are shown on the Workbench. Once you are satisfied with the metrics and their values that are received, stop the current process and start the Machine Agent to view the metrics being reported on the metric browser.   ... View more

What is the use case for using "taskSchedule" for extensions? How do I configure "taskSchedule"?   Contents Why use "taskSchedule" to monitor intervals? How do I configure "config.yml" to use task schedule mode?  Details to know about using "taskSchedule"   Why use "taskSchedule" to monitor intervals? The execution frequency for an extension is typically set using the element <execution-frequency-in-seconds> in the monitor.xml . However, this value cannot be higher than 300 seconds. For use cases where an artifact needs to be monitored with an interval greater than 300 seconds, taskSchedule should be used.   The SDK provides a mechanism to cache the metrics and retain them for a maximum period of 15 minutes. When taskSchedule is configured, the Machine Agent still runs the extension as configured in <execution-frequency-in-seconds>. However, the extension returns cached values until the cache refreshes, as specified in the taskDelaySeconds field of the configuration.   How do I configure config.yml to use task schedule mode? In order to use task schedule mode, the following line should be included in the config.yml . taskSchedule: numberOfThreads: taskDelaySeconds:   numberOfThreads is the size of the core thread pool that is used by the Scheduled Threadpool Executor. The default is 1. taskDelaySeconds is the scheduling interval in seconds.   Here is an example to schedule tasks for every 12 minutes (12 * 60 seconds) taskSchedule: numberOfThreads: 1 taskDelaySeconds: 720   Details to know about using "taskSchedule" The ideal scenario for using taskSchedule is when you want to fetch current metrics at an interval of more than 300 seconds (5 minutes). The cached metrics are only retained for 15 minutes, after which they expire and are re-cached in the next scheduled run. If taskDelaySeconds is configured to be more than 15 minutes, the extension will report null values which will lead to gaps on the Metric Browser. ... View more

Metric Transformers in the  Extensions Commons Library   The Java Extension SDK provides an automated utility that allows extensions developers to transform a metric name and value as it would be represented in the Metric Browser. These transformers include the  Alias, the Multiplier, the Delta, and the Convert.   Contents How should the transformers be configured? List of transformers Alias Multiplier Delta Convert   How should the transformers be configured? In the metrics.xml , the transformers should be specified in the following manner.   <stat url="/nitro/v1/stat/lbvserver" rootElement="lbvserver" alias="Load Balancing Server Metrics"> <metric attr="cursrvrconnections" alias="Server Connections"/> <metric attr="memoryInMBytes" alias="Memory in KB" multiplier="1000"/> <metric attr="throughput" delta="true" /> <metric attr="state"> <convert str="DOWN" value="0"/> <convert str="UP" value="1"/> <convert str="UNKNOWN" value="2"/> </metric> </stat>   In the config.yml , the transformers should be specified in the following manner. metrics: - name: “cursrvrconnections” alias: “Cursor RV Connections” delta: true multiplier: 1000 convert: “DOWN”: 0 “UP”: 1 “UNKNOWN”: 2   Note that multiple transformers can be applied to the same metric as follows: < metric attr= "cursrvrconnections" alias= "Server Connections" multiplier= "10" delta= "true" />   Please note the following: It is not mandatory to specify any of these transformers. By default, a metric does not have an alias and will be named as-is from the artifact being monitored. The default value for the multiplier is always 1. The default value for the delta is always false. A metric that yields text values will simply be skipped if a convert transformer isn’t specified.   On calling transformAndPrintMetrics(List<Metric> metrics) in com.appdynamics.extensions.MetricWriteHelper , the SDK automatically applies any configured transformers before publishing these metrics.   List of transformers Alias The Alias transformer can be used to replace a metric’s name. Often, metrics are represented by ambiguous names in the artifacts being monitored, as evident in the example above. In this case, cursrvrconnections will be represented as Server Connections in the Metric Browser. Multiplier The Multiplier transformer can be used to multiply the original metric value by a configured factor. From the example above, consider that an artifact returns memory in MB and a requirement is to monitor this metric in KB. A multiplier of 1000 can be applied to this metric to satisfy this requirement. Delta Consider an ever-increasing metric value and a requirement is to monitor the number of units by which this metric increases every minute. A Delta transformer can be applied in this case. This transformer compares the value of a metric at minute X with its value at minute X-1 and publishes the difference as a metric value.   NOTE | Every time the extension is run, the first value will not be reported if delta is true. Convert The Convert transformer can be applied to metrics that return a text value from an artifact’s API. These text values can be represented as numeric values. From the example above, DOWN will be represented with a value of 0, UP with 1 and UNKNOWN with 2 for the state metric.   ... View more

Table of Contents Use Case Configuration   Use case The AppDynamics Controller currently supports only ASCII characters in the metric path. There are several reserved characters that are not supported and can cause undesirable behavior if present in the metric path.   The characters separated by "|" in the metric path are called tokens. The Metric Char Replacement can be used on all metric paths that belong to any of the following scenarios : The tokens have characters outside ASCII range (unicode characters) The tokens have some reserved characters The user wants to replace some text across all tokens with shorter or more meaningful text   These are things to consider when forming a metric path: Non-ASCII characters are not allowed. The default metric separator for any metric is “|” and an occurrence of “|” creates a new level of hierarchy in the metric tree. Therefore, unless “|” is actually meant for creating hierarchies, it should not be part of a metric token. “:” is similar to “|” in that it will create a new hierarchy. “,” is a special character and cannot be used in the metric path.   Configuration In order to use the Metric Char Replacement feature of the Java SDK for AppDynamics Extensions, the following section must be included in your config.yml :   metricPathReplacements: - replace: replaceWith:   Note: The “ replace ” value cannot be empty. The “ replaceWith ” value cannot contain non-ASCII characters or “ | ”, “ , ”, “ : ”.   Example:     metricPathReplacements: - replace: "&" replaceWith: "" - replace: "-" replaceWith: "_"   The example here configures two replacements: replace “&” with “” and replace “-” with “_”. I f a metric has tokens like “Read&Write”, it will get converted to “ReadWrite” and tokens like “wait-time” will get converted to “wait_time”.   The metric replacement module also loads some default replacements:  “ | ”, “ , ”, “ : ” are replaced with “” (empty string). These default values can be overridden by configuring them in your config.yml to be replaced with another character.   For M etric Char Replacement to work correctly, the path should not be formed in the extension’s code. Rather, the extensions commons library methods should be used to form the metric path. There are two ways to do this: Directly use the Metric constructor with signature. public Metric(String metricName, String metricValue, Map<String, ?> metricProperties, String metricPrefix, String... tokens) Use MetricPathUtils.buildMetricPath(String metricPrefix, String... metricTokens) to first build the metric path and then create the Metric object using the Metric constructor that accepts the metric path created earlier. ... View more

Table of Contents Use Case Configuration Events Service Client Creating a Schema Retrieving a Schema Deleting a Schema Publishing Events   Use Case The AppDynamics Metric Browser only supports numerical values for metrics. In order to overcome this issue and store and monitor non-numerical values, AppDynamics has the Events Service platform. The Events Service can now be accessed and used through extensions by using the Events Service client from the Java SDK for AppDynamics Extensions.   The Events Service client uses the AppDynamics Analytics Events API to send non-numerical values to the AppDynamics platform. Once this information is sent to the Events Store using the client, you can query it via the Controller UI. Configuration In order to configure the Events Service client, you need to fill certain fields in the config.yml to initiate a connection with the Analytics Events API. These fields are configured as follows: eventsServiceParameters:     host:                         # Events Service Host     port:                         # Events Service Port     globalAccountName: # Found in Controller -> Settings -> License -> Account     eventsApiKey:           # Generated from Controller -> Analytics -> Configuration -> API Keys     useSsl:                      # true/false   Any existing SSL and/or proxy configurations in the config.yml are automatically used while initiating this connection. Events Service Client The Events Service Client can perform C.R.U.D. operations. The following section explains how a user can perform these operations through an extension. The Events Service client can be obtained and used in the following manner: ABaseMonitor.getContextConfiguration().getContext().getEventsServiceDataManager() For the purposes of this article, the Log Monitoring Extension will be used as an example. Previously, if the extension captured a match, it would only send the number of match occurrences to the Metric Browser. The extension now uses the client to send both the number of matches and the actual log matches as strings to the Events Service API. Consider the following log snippet: [Thread-1] 29 Apr 2014 12:31:18,647 INFO DynamicServiceManager - Scheduling DynamicServiceManager at interval of 30 seconds [Thread-1] 29 Apr 2014 12:31:18,647 DEBUG LifeCycleManager - Started service [DynamicServiceManager] [Thread-1] 29 Apr 2014 12:31:18,647 INFO LifeCycleManager - Starting services [Thread-1] 29 Apr 2014 12:31:18,660 DEBUG JMXService - ###### Using config from controller for JMX operations [Thread-1] 29 Apr 2014 12:31:18,665 INFO ServerMBeanManagerVersion2 - Initialized MBean Finder with delay=120 secs [Thread-1] 29 Apr 2014 12:31:18,679 DEBUG MemoryMetricGenerator - Identified minor collection bean :ParNew   Creating a Schema The first step is to create and register a custom schema with the Analytics Events API using the below method. public void createSchema(String schemaName, String schemaBody)   The schema defines the overall structure of an Event Type by field and data type. In this case, let's create a schema called LogSchema with the following fields: - logDisplayName - logDirectory - searchPattern - match   The schema body must be passed to the API as a JSON formatted name-value pair, as follows: {  "schema":  {    "logDisplayName":"string",    "logDirectory":"string",    "searchPattern":"string",    "match":"string"  } } The supported data types are string, integer, float, boolean and date in either ISO 8601 or UNIX epoch format. Note that the following two timestamp fields are automatically added to every custom schema: - eventTimestamp (the time at which an event occurs) - pickupTimestamp (the time at which the event is received by the Events Service)   Once you have defined all the information, this method can be called and used in the following manner:  ABaseMonitor.getContextConfiguration().getContext().getEventsServiceDataManager().createSchema( schemaName, schemaBody)   Retrieving a Schema Once a schema has been created, the below method can be used to retrieve its details. A JSON formatted name-value String representing the schema is returned, identical to the body described in point 1. public String retrieveSchema(String schemaName) This method can be used in the following manner: ABaseMonitor.getContextConfiguration().getContext().getEventsServiceDataManager().retrieveSchema( schemaName)   Updating a Schema This method is used to update an existing schema using an HTTP Patch operation. public void updateSchema(String schemaName, String schemaUpdates)   Consider replacing the logDisplayName field in the schema body with logName and adding a new field called fileEncoding . These updates are passed to the client as a String in the following format: [  {    "add": {      "fileEncoding": "string"    },    "rename": {      "logDisplayName": "logName"    }  } ]   This method can be used in the following manner: ABaseMonitor.getContextConfiguration().getContext().getEventsServiceDataManager().updateSchema( schemaName, schemaUpdates)   Deleting a Schema These methods can be used to delete one or more previously registered schemas.  They can take a single schema as input or a list of schemas. public void deleteSchema(List<String> schemaNames) public void deleteSchema(String schemaName) These method can be used in the following manner: ABaseMonitor.getContextConfiguration().getContext().getEventsServiceDataManager().deleteSchema( schemaName) // OR ABaseMonitor.getContextConfiguration().getContext().getEventsServiceDataManager().deleteSchema( listOfSchemaNames)   Publishing Events The Publish Events API call takes a collection of events and stores them in the Events Service storage. The data must comply with an existing schema. If the event data doesn't match an event schema, the API returns a 400 bad request. public void publishEvents(String schemaName, List<String> eventsToBePublished) For this example, consider monitoring the log snippet for two patterns: \\.*DynamicServiceManager.*\\ \\.*JMXService.*\\   The events should look like the following: [{    "logDisplayName":"Dynamic Service Manager Logs",    "logDirectory":"Some directory",    "searchPattern":"\\.*DynamicServiceManager.*\\",    "match":"[Thread-1] 29 Apr 2014 12:31:18,647  INFO DynamicServiceManager - Scheduling DynamicServiceManager at interval of 30 seconds" },{    "logDisplayName":"JMX Service Log",    "logDirectory":"Some directory",    "searchPattern":"\\.*JMXService.*\\",    "match":"[Thread-1] 29 Apr 2014 12:31:18,660  DEBUG JMXService - ###### Using config from controller for JMX operations" }] The Events Service client publishes events in batches of 1000 events to conform to the Controller's custom event ingestion limits.   This method can be used in the following manner: ABaseMonitor.getContextConfiguration().getContext().getEventsServiceDataManager().publishEvents( schemaName, eventsToBePublished)     Detailed information about the Analytics Events API can be found here: Analytics Events API ... View more

How is HttpClient used in the extensions commons library?   This document explains the httpClient used by the extensions commons library, part of the Java SDK for AppDynamics Extensions.   Table of Contents Goal Usage Configuration   Goal Most of the extensions collect metrics from an HTTP(s) endpoint. Instead of creating an httpClient in every extension, we have created an httpClient for the commons library  that can be used in all the extensions.   Usage CloseableHttpClient httpClient = configuration.getContext().getHttpClient() , where configuration is an object of the MonitorContextConfiguration class.   Configuration To use httpClient in any extension, provide the following configuration in the config.yml file: Server Configuration Connection Configuration   Server Configuration The two servers configured below are valid. Config1 is preferred over Config2.   Config1 servers: - uri: "" username: "" password: "" encryptedPassword: ""   Config2 servers: - host: "" # Avoid this, use uri instead port: "" # Avoid this, use uri instead useSsl: false # Avoid this, use uri instead. username: "" password: "" encryptedPassword: ""   Configuring multiple servers Configuring multiple servers in a single config.yml is also supported. servers: - uri: "" username: "" password: "" encryptedPassword: "" # Uri is preferred instead of host-port-useSsl combo. - host: "" # Avoid this, use uri instead port: "" # Avoid this, use uri instead useSsl: false # Avoid this, use uri instead. username: "" password: "" encryptedPassword: ""   A username and password can also be provided or you can provide the encrypted password and leave the password field empty.   NOTE: You can add an encrypted password for each server, but the encryptionKey will be the same for all the servers as defined in the config.yml file.   If you provide values for both the password and encryptedPassword, the extension will give precedence to the value provided in the password field and the encryptedPassword will be disregarded.   If you would like to use HTTPS , specify protocol as https in Config1 or change the value of useSsl to true in Config2.   Connection Configuration Connection configuration is optional , but enables you to have more choices when trying to establish a new connection with a server. Like the encryptionKey, this section is universal for all the servers listed in the config.yml file. connection: socketTimeout: 3000 connectTimeout: 1000 sslProtocols: ["TLSV1.2"] sslCertCheckEnabled: true sslVerifyHostname: true sslCipherSuites: [] sslTrustStorePath: "" sslTrustStorePassword: "" sslTrustStoreEncryptedPassword: "" sslKeyStorePath: "" sslKeyStorePassword: "" sslKeyStoreEncryptedPassword: ""   Flag Description Remarks socketTimeout Time limit in milliseconds for a socket to time out after establishing a connection   connectTimeout The connection will timeout after this number of milliseconds   sslProtocols Array of strings of all the protocols to be followed Defaults to "default" sslCertCheckEnabled Set this to true to enable Certificate checks Ideally, it is suggested that both sslCertCheckEnabled and sslVerifyHostname listed about should be true for security reasons. sslVerifyHostname Set this to true to enable host name verification   sslTrustStorePath Path to the SSL TrustStore Defaults to machine-agent/conf/extensions-cacerts.jks sslTrustStorePassword Truststore password in cleartext The keystore needs to have either sslTrustStorePassword or   sslTrustStoreEncryptedPassword sslTrustStoreEncryptedPassword Encrypted TrustStore password   sslKeyStorePath Path to the SSL KeyStore Defaults to machine-agent/conf/extensions-clientcerts.jks sslKeyStorePassword SSL Keystore password in cleartext   sslKeyStoreEncryptedPassword Encrypted SSL Keystore password     ... View more

What extension Health Checks generate logs I can use for debugging issues?   The Java SDK for AppDynamics Extensions runs a few checks to validate the Application and Machine Agent configuration and to ensure an error-free run of any configured extensions. These checks on validation (or failure) log messages in the Machine Agent logs to help debug any issues. These checks are primarily categorized into:   RunOnce Check: Runs only once on the start of the extension. RunAlways Check:  Run periodically based on the defined frequency. RunOnce Check AppTierNode Check: Ensures correct Machine Agent and SIM configuration with the following checks: ControllerInfo: Controller information can be configured either using System properties or via the controller-info.xml file present in the path <MachineAgent>/conf . Extension checks verify data from both places. In case the Controller information is not found in either of the places, then the missing ControllerInfo error message is logged. SIM Enabled: From the controller-info obtained in the previous step, this checks if SIM is enabled or not. Application/Tier/Node: Based on the result obtained in the previous step: When SIM is disabled, configuring the App/Tier/Node is mandatory, or an error will be reported. When SIM is enabled, App/Tier/Node does not need to be configured. ExtensionPathConfig Check: Performs the following checks on the extension path configuration: Metric Prefix: Logs errors if the metric prefix retrieved from config.yml is null or empty. Tier ID: This check is performed as follows: When SIM is enabled, there is no check for Tier ID. When SIM is disabled, the Tier ID set in config.yml is verified with the TierName (or the corresponding Tier ID)  in controller-info.xml . Machine Agent Availability Check : When SIM is disabled, this checks whether the Machine Agent Availability metric reports 1 or not. A GET request to the Controller for the following URL checks the MA availability: /controller/rest/applications/ApplicationName/metric-data?metric- path=ApplicationInfrastructurePerformance|TierName|Agent|Machine|Availability&time-range- type=BEFORE_NOW&duration-in-mins=15&output=JSON   RunAlways Check  MaxMetricLimit Check: Machine Agent metrics limit is a frequently encountered error. Whenever this error occurs, the following message appears in the Machine Agent logs: ERROR ManagedMonitorDelegate - Maximum metrics limit reached [450] no new metrics can be created. This exception will not repeat until restart. The MaxMetricLimit check logs an error on any occurrences of this string in the Machine Agent logs.  MetricBlacklistLimit Check: A Blacklist limit error is logged as in the following warning:  WARN ManagedMonitorDelegate - Metric registration blacklist limit reached This check looks up the Machine Agent logs for any occurrences of this string and, if found, logs the message and the error details. ... View more