Configure and Download an Agent Package

apmsaas
HID_Download_Agent_Package
Agents collect application and infrastructure metrics. An agent package is a deployable set of agent binaries and configuration files in ZIP or TAR format, and contains the installation instructions. The Agent Controller is delivered as a
DX APM
agent extension. The Agent Controller manages agents running on the same host where the Agent Controller runs. By default, the Infrastructure Agent contains the Agent Controller. You can add the Agent Controller extension to Java agents. During run time, the Agent Controller starts as a subprocess of the agent monitoring process.
After you configure and download the agents, APM Command Center detects the agents through the Agent Controller. You manage the agents, which are now visible, in APM Command Center. Agent management in APM Command Center includes the following items:
  • Create agent packages
  • Configure agent packages
  • Save those package configuration settings for later use.
  • Upgrade the agent with the new package version
  • Run the diagnostics that provide reports on the environment that the agents run in
  • View filtered agent collections
  • Filter the agents by the operating system and monitoring environment
Whether or not you use the Agent Controller extension, the agents continue to send metrics and that is visible in
DX APM
. For more information, see Configure the Agent and Review the Agent in APM Command Center.
If you connect your agents through a cloud proxy, the metrics are sent via cloud proxy to
DX APM
. The Agent Controller also connects to the Configuration Server through the cloud proxy. For more information about cloud proxy, see Migrate Agents Using Agent Proxy.
Download as many agent packages for application and infrastructure monitoring as you need for comprehensive metric collection.
Select the required agents to monitor applications or the infrastructure:
  • Applications
    Shows the agents that monitor your applications and application servers. For more information, see Configure Application Server to Use the Java Agent.
  • Infrastructure
    Shows the agents and extensions that monitor the environment hardware.
    You can also select agents for applications that you monitor directly through the cloud.
    Start monitoring your environment with these agents immediately by following the instructions. You do not need to download an agent package for these agents.
Configure and Download an Agent Package
Select an agent for download. Configure the package and save your package configuration for later use.
Follow these steps:
  1. Select
    Agents
    in the left pane under
    Settings
    , and then select
    Download Agent
    .
    The
    Select Agent to Download
    menu opens.
  2. In the
    Environment
    section, select one of the operating systems to view the available agents for that operating system only:
    OS Type:
    • Unix
    • Windows
    Process:
    You can select any of the following processes:
    DX APM
    Infrastructure Agent, CTG Server,
    DX APM
    .Net Agent, GlassFish, Interstage, JBoss, JBoss NoRedef, Other Java Application, Tomcat, Tomcat NoRedef, WebLogic, WebLogic NoRedef, WebSphere, WebSphere NoRedef.
    OS Name:
    The following options appear when you select:
    OS Type
    as
    Unix
    , and
    Process
    as
    DX APM
    Infrastructure Agent
    • AIX
    • Linux OS/390
    • Linux x64
    • Solaris SPARC V9
    • Solaris x64
  3. Select an agent from the
    Applications
    or
    Infrastructure
    tab.
    Hover over the
    information
    icon to learn more about the agent.
    • To download an
      Applications
      agent without configuring it, select the agent.
      The
      Install
      screen opens and the agent package downloads immediately.
      If the agent does not automatically download, select
      Download Manually
      to download the agent.
    • (Optional) To configure an
      Applications
      agent before downloading it, select the
      Settings
      icon.
      1. Select extension options for the agent, if any appear for that agent. Some extensions require properties configuration to work in your environment. These properties, if any, become visible after you select the extension.
        You can configure the Browser Agent to inject HTML snippets. This configuration enables
        App Experience Analytics
        to collect customer analytics for your web application. To drill down from AXA to the corresponding APM transaction data, first configure the integration between
        DX APM
        and AXA from the AXA application.
        DX APM
        then automates the connection with AXA when you create an app for a Browser Agent. You can also configure the Browser Agent after you download it. The install instructions and configuration instructions for extensions are available in the
        installInstructions.md
        file of the downloaded archive for later configuration.
        You can configure the Log Correlation extension to inject the correlation ID into an application server log. This configuration enables you to increase visibility into application performance issues by correlating your application server log to transaction traces and error and stall snapshots. For more information, see Log Correlation.
        You can embed an Agent Controller into the Java Agent package by adding the
        Agent Controller
        extension from the
        Settings
        icon. However, we recommend that you download the Infrastructure Agent along with your Java Agent instead to optimize your agent, Agent Controller, Configuration Server connection. The Infrastructure Agent contains an embedded Agent Controller. For more information, see Configure the Agent and Review the Agent in Command Center.
      2. Search for previously saved agent package configuration settings by selecting
        Pre-Configured Options
        . For information about managing saved agent package configurations, see Manage Saved Agent Package Configuration Settings.
      3. Select
        Save this Configuration
        to save these agent package configuration settings for future use.
      4. Select
        Download and Install
        .
        The agent package downloads immediately.
    • To configure and download an
      Infrastructure
      agent extension, select the agent.
      Extension configuration options appear.
      1. Select extension configuration settings as needed.
      2. Name your agent package configuration settings.
      3. Select
        Save this Configuration
        to save your new settings for future use.
        Search for previously saved agent package configuration settings by selecting
        Pre-Configured Options
        . For information about managing saved agent package configurations, see Manage Saved Agent Package Configuration Settings.
      4. Select
        Download and Install
        .
      5. Deploy the package to the application server.
        The package registers in Command Center after it is deployed. For more information about configuring the agent in Command Center, see Configure the Agent and Review the Agent in Command Center.
  4. To return to the previous screen and select another agent, select either
    Choose Another Agent
    or
    Back to Agent List
    .
Manage Saved Agent Package Configuration Settings
Select an agent and configure the agent package. Save the configuration package for later use and download the agent package when you need it. Delete or modify the agent package configuration settings as needed.
You must be an administrator to save and delete package configurations.
Modify Package Configuration Settings
View and modify existing package configuration settings.
Follow these steps:
  1. To view saved agent package configuration settings, select
    Saved Configurations
    .
    A list of saved agent package configuration settings appears.
    Sort the existing package configuration settings by
    Configuration Name
    ,
    Package
    ,
    Platform
    ,
    Environment
    , or
    Last Update Date
    .
  2. Select the
    Pencil
    icon of a package to make configuration changes.
    The configuration settings for that agent package appear.
  3. (Optional) select the
    Pre-Configured Options
    dropdown to select and view other saved configuration settings for that package.
  4. Make any configuration changes that you require.
  5. Select
    Save this Configuration
    to override the existing settings.
  6. Select
    Back to Agents List
    to return to the previous menu.
Delete a Saved Agent Package Configuration
Delete existing agent package configuration settings.
Follow these steps:
  1. Select
    Saved
    Configurations
    .
  2. Locate the package configuration settings that you want to delete.
  3. Select the
    Trash
    icon that is aligned with that package.
    The package deletes.
Configure the Agent and Review the Agent in APM Command Center
As an administrator, you must download an agent with the Agent Controller to connect to Command Center. You can do this using one of two methods:
  • (Java Agent only) Configure the Java Agent to add the Agent Controller as an extension.
    1. To embed the Agent Controller with the Java Agent, select the
      Settings
      icon next to the Java Agent.
    2. Select
      Agent Controller
      from
      Agent Components
      .
    3. Download and install the agent.
  • (Any other agent) Download the Infrastructure Agent along with your other agent onto the same application server.
To optimize the agent, Agent Controller, and Configuration Server connection, download your agent and the Infrastructure Agent onto your application server. The Infrastructure Agent contains the Agent Controller. The Agent Controller then automatically connects to Command Center after you download and unpack both agents onto your application server. If you deploy multiple agents with the Agent Controller, only one Agent Controller runs at any given time. The Agent Controller starts as the second part of the agent monitoring process. Do not add the Agent Controller to each individual agent package that is monitoring an application.
You can access APM Command Center from
DX APM
. Verify the agent connection details in APM Command Center. You can further add or create packages, and push them to your application servers through APM Command Center.
Follow these steps:
  1. In
    DX APM
    , go to
    Agents
    and select
    Download Agent
    .
  2. Download the agent to your application server.
  3. Select and download the
    Infrastructure Agent
    .
  4. Unpack both packages and restart the application server.
  5. From the
    DX APM
    Home
    screen, select the
    All My Universes
    drop-down.
  6. Select
    APM Command Center
    from the list.
    A new tab opens to the APM Command Center
    Home
    screen.
  7. Verify that your agent appears active in the
    APM Command Center Summary
    . The agent appears only after you successfully deploy the agent package onto the application server.
You can now edit the agent, create reports, and upgrade and push the agent package.
Agent Controller Configuration Properties
  • Communication
    • introscope.agent.acc.controller.configurationServer.url=<acc server endpoint>
    • introscope.agent.acc.controller.configurationServer.token=<token>
  • Server port
    • introscope.agent.acc.controller.agentDiscovery.port=51914
  • Logging
    • introscope.agent.acc.controller.logging.level.com.ca.apm=INFO
    • introscope.agent.acc.controller.logging.file=${introscope.agent.logs.dir}/apmccctrl.log
  • Heap settings
    • introscope.agent.acc.controller.heap.settings=-Xmx64m
Agent Controller Troubleshooting
Upgrade
After the controller has been upgraded (with an agent version upgrade, or by adding a controller bundle version), it will be considered as a new controller instance by ACC. All existing messages sent to the previous controller will be lost and not processed (e.g., agent package update request).
Important log messages:
  • Success
    • [INFO] [IntroscopeAgent.AccControllerManagementService] Starting ACC Controller Management Service
    • [INFO] [IntroscopeAgent.AccControllerManagementService] AccControllerWatcher ACC Controller Process is up and running
  • Failure
    • [ERROR] [IntroscopeAgent.AccControllerManagementService] AccControllerWatcher Failed to launch ACC Controller Process
    • [ERROR] [IntroscopeAgent.AccControllerManagementService] AccControllerWatcher ACC Controller Process launched by agent is not available
  • Debugging
    • Agent profile log4j.logger.IntroscopeAgent.AccControllerManagementService=DEBUG, logfile
    • Bundle properties introscope.agent.acc.controller.logging.level.com.ca.apm=DEBUG
Agent Controller Known Issues
  • Supported with JVM 1.7 and higher
    Workaround:
    Set to one of the environment variables (JAVA_HOME, JRE_HOME, JDK_HOME) to Java version >= 1.7.
  • No-redef bundles and application
    Hot change is not supported. The monitored application/agent must be restarted.
  • Controller runs as child process of monitored process/agent
    We recommend using the infrastructure agent in this case.
  • Infrastructure Agent
    The Infrastructure Agent agent does not support the bootstrap layout.
  • Agent property override
    Supported overrides
    • Via ACC: edit agent package
    • Via CLI: using
      –D<propertyname>=value
    Not supported overrides
    • Local modifications of IntroscopeAgent.properties (v1 bundles), and bundle.properties (v2 bundles) is not supported.
    • Local changes will be lost on a new agent package application.