Discussion Feed

Table of Contents Use Case Configuration Notes   Use Case 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.   Configuration 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   Note The ideal scenario for using taskSchedule is to use it 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. This will lead to gaps on the Metric Browser. ... View more

Table of Contents Introduction Configuration Alias Multiplier Delta Convert   Introduction 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 following: Alias Multiplier Delta Convert   Configuration 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.   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 : Everytime 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

Table of Contents Scope Goal Usage Configuration   Scope This document explains the HttpClient used by the extensions commons library, part of the Java SDK for AppDynamics Extensions.   Goal Most of the extensions collect metrics from an HTTP(s) endpoint. Instead of creating a HttpClient in every extension, we have created an HttpClient in 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, the following configuration needs to be provided in the config.yml file: Server Configuration Connection Configuration   Server Configuration The two servers configured below are valid and 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 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 that 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 This section is optional , but enables you to have more choices when trying to establish a new connection with a server. This section, just like the encryptionKey, 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

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 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, otherwise an error will be reported. When SIM is enabled, App/Tier/Node do 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 in two steps: When SIM is enabled, there 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 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

Table of Contents Use Case Configuration ControllerInfo CustomDashboard Post Configuration   Use Case AppDynamics Extensions will now support automatically uploading a pre-built dashboard with every extension. This feature will help customers use an extension to extract all the listed metrics and provide an overview of how the product is doing in terms of certain key metrics. All dashboards can be updated and more data can be added to increase the visibility of the metrics provided by the extension.   Configuration   In order to upload a dashboard to the Controller, you need to provide some information about the Controller that will help the extension log in and upload the dashboard to the Controller.   Each new extension is going to be equipped with two dashboard files: one for the Standalone Machine Agent model and one for the Server and Infrastructure Monitoring (SIM) model. While configuring the extension, you will need to configure the following sections:  controllerInfo and customDashboard.   ControllerInfo This section requires you to fill out information about the Controller, which in turn is used to make sure that the extension can establish a connection to the Controller and upload the dashboard. The extension pulls the information in the following order from the following resources: controller-info.xml System Properties Config.yml   You need to update the following section in the config.yml : controllerInfo: controllerHost: "" controllerPort: "" account: "" username: "" password: "" encryptedPassword: "" encryptionKey: "" controllerSslEnabled: "" enableOrchestration: "" uniqueHostId: "" accountAccessKey: "" machinePath: "" simEnabled: "" applicationName: "" tierName: "" nodeName: ""   As you start your agent, a number of the fields will get auto-populated but there are a few fields that need to be manually populated. These are:   username: "" password: ""   These fields are required for the Machine Agent to be able to log in and upload the dashboard. Once all of this information is provided, populated and validated, the extension will upload the dashboard to the Controller.   After filling it out, this section should look like this:       CustomDashboard Similar to ControllerInfo, another section called customDashboard needs to be updated in order to make sure that a dashboard can be uploaded to the Controller from the extension. customDashboard: enabled: true dashboardName: "Custom Dashboard" pathToSIMDashboard: "monitors/<ExtensionName>/simDashboard.json" pathToNormalDashboard: "monitors/<ExtensionName>/maDashboard.json" periodicDashboardCheckInSeconds: 300   If enabled is false, the dashboard will not upload. If dashboardName is not present, the extension Monitor Name will be used as the dashboard name. The two fields that you should verify are the pathToSIMDashboard and pathToNormalDashboard . Both of these fields need to point to two files that are provided with the extension. If there are any changes made to these files, you must make sure that the changes are saved to these files, and in the case they are replaced with new files, their path should be updated in the config.yml . As the extension sits in the Machine Agent, the path after the base directory of the Machine Agent is needed. Make sure you have the correct file separator:  (\) for Windows and (/) for Linux- based operating systems. Dashboards cannot be overwritten on the Controller. Therefore, if a dashboard is already present on the Controller, you will not be able to upload another dashboard with the same name. If you make any changes to the dashboard file to suit your needs, you should save the dashboard.json file and delete the current dashboard on the Controller. By default, the extension will check if a dashboard is present on the Controller every 5 minutes (300 seconds), and if it is not present, it will attempt to upload it. You have the option to increase this limit to however long or short you would like it to be using the periodicDashboardCheckInSeconds parameter.   Post Configuration After filling in both these sections and configuring the rest of the extension to its specific needs, you can start the Machine Agent to gather metrics and check if the dashboard has been uploaded and is being populated with the correct data. Every extension that comes with a dashboard has some preconfigured metrics set up to show up in the dashboard. If any changes are made to the dashboard file, please delete the existing dashboard present on the Controller so that the extension can upload a new copy of the dashboard with the your changes. If you would like to compare the differences after making changes to the dashboard file, the name of the dashboard can be changed in the config.yml under the customDashboard section. This name should be a different name from the last dashboard and a dashboard with this name should not be present on the Controller. Once the extension hits the periodic dashboard check limit, it will again check if the dashboard with the new name is present. If not, it will upload this new dashboard which may then be used for further comparisons. Each extension will have specific metrics that may have been chosen to be displayed on the dashboard. If you would like to see more metrics, they can be manually added to the same dashboard on the Controller. If any changes are made to the metric names/aliases in the config.yml , those changes need to be replicated in the dashboard.json files since they are preconfigured to look for metrics with the default metric names/aliases that are provided with a new copy of the extension. If these changes are not replicated, there is a good chance that the dashboard widgets that are associated with the corresponding metrics may not work.   ... View more