Deploy Agent Packages Using APM Command Center

apmsaas
APM Command Center lets you create and deploy agent packages onto application servers from APM Command Center. Packages are a deployable set of agent binaries and configuration files in ZIP or TAR format. Each package comprises several bundles. A
bundle
is a compact piece of agent functionality.
The terms bundle and extension are interchangeable in APM Command Center.
You complete the following high-level steps to deploy agent package.
  1. You can create a package to fit your target application environment, add and remove bundles, and configure the package to your needs in either
    DX APM
    or APM Command Center. For more information about using
    DX APM
    to download an agent, see Configure and Download an Agent Package.
  2. You download the package as an archive file to install the agent. Refer to the installation instructions in the UI to install the agent.
  3. The agent then reports the package information in APM Command Center and the metrics in Application Performance Management.
  4. Later, you can import and configure the bundles and upgrade the packages. For more information about package management, see Manage Agent Packages and Bundles Using APM Command Center.
This article contains the following topics:
Create an Agent Package
To monitor your application environment, create an agent package. The Agent Controller manages the agent in APM Command Center. Agent management includes creating agent packages, upgrading agents, and displaying filtered agent collections. Additionally, the Controller helps with running diagnostics that provide reports on the environment that the agents run in.
The Agent Controller is embedded in Infrastructure Agent packages only. The Agent Controller manages agents in APM Command Center. To deploy the Agent Controller for any other agents (for example, the Microsoft .NET Agent or Java Agent), you must deploy the Infrastructure Agent along with that other agent. For information about adding the Agent Controller as a bundle to the Java Agent, see Configure and Download an Agent Package.
At any time during the process, you can select
Previous
to return to the previous screen.
Follow these steps:
  1. Go to the
    Packages
    tab in APM Command Center and select
    New
    .
  2. The Agent Builder opens.
  3. Enter a
    Package
    Name
    and
    Description
    .
  4. Select an
    Operating System Type
    (UNIX or Windows).
  5. Select a
    Process
    . The Process defines the application environment that you want to monitor.
    Depending on your operating system and application environment, you may see another option to select the secondary operating system.
  6. If necessary, select the
    Secondary OS Name
    (AIX or Linux).
  7. Select an
    Agent Version
    .
    When you select the
    Agent Version
    , you can add only the bundles compatible for that agent version to the package. By default, the system selects the bundles that are used, but you can change these bundles.
  8. (Optional) If you want to specify the cloud proxy, add the cloud proxy address to the
    Cloud Proxy
    field. Add the cloud proxy if you want your applications and agents to communicate through a firewall to the gateway. Otherwise, leave this field empty. For more information about cloud proxy, see Migrate Agents Using Cloud Proxy.
  9. Select
    Done
    to save the package.
Now that you created a package, add or remove bundles to the package and configure agent functionality.
Use a Bundle in a Package
Each agent package comprises several bundles. A bundle represents a compact piece of agent functionality. For example, a bundle exists for SQL, web services, HTTP backends, servlet, and JSP.
Customize your package in APM Command Center:
  • Add and remove bundles when you create a package and edit the bundles later
  • Change the bundle configuration
  • Edit the default installation instructions in the UI for other users to use as a reference
In the
Select Bundles
tab of the Agent Builder, two columns list available and selected bundles:
  • Available Bundles
    Optional bundles for special monitoring that are compatible with your environment.
    Example
    The LeakHunter bundle
  • Selected Bundles
    Default, preselected bundles that are required or recommended for monitoring in your environment.
    Example
    The Struts bundle for Tomcat.
The bundles that are listed in both columns are grouped according to their type:
  • Core
    Core monitoring components, such as the Java Agent binaries or APM Command Center extension.
  • Environment
    Depending on the platform, the Environment group contains bundles that monitor the application server.
  • Features
    Various APM monitoring features to enhance metrics visibility.
  • Custom
    Unofficial bundles. For more information, see Add Custom Bundles.
When you select a bundle, information about the bundle functionality appears. If the selected bundle depends on other bundles, these bundles are highlighted in APM Command Center.
For a full list of bundles that are included in the installation, see List of Bundles.
Add a Bundle to a Package
Before you can configure a bundle, you must add it to your agent package.
Follow these steps:
  1. Go to the
    Packages
    tab in APM Command Center.
    A list of packages appears.
    Next to each package name, you can see the number of active agents and total agents that the package is attached to.
  2. Select the package that you want to configure.
    Basic information for the package displays.
    The
    Versions
    section of the Configuration card shows the agent number and agent version that the package is attached to.
  3. Select
    Edit
    .
    The Agent Builder opens.
  4. To add or remove bundles and to change the bundle configuration, select
    Customize
    .
    The
    Select Bundles
    tab opens.
  5. Select the bundles appropriate for your monitoring needs, and select
    Add
    .
    Filter the bundles by property name using the search function.
  6. Select
    Done
    to save the bundles in the package.
Configure Bundle Properties and Installation Instructions in APM Command Center
You configure a bundle by editing current
IntroscopeAgent.profile
properties or by adding new ones. You can edit the bundles and configuration instructions when you create the package or later. APM Command Center shows the installation instructions for the created package. These instructions comprise all installation instructions for the individual bundles that are included in the package. Edit these instructions to provide other users with information specific to the agent deployment in your environment. For text formatting, use markdown language syntax. For more information, see Markdown language syntax.
The changes that you make in APM Command Center are specific to the agent package that you edit. These changes do not propagate to other agent packages or when you upgrade the agent package. If you make manual changes by using the agent package files ystem, these changes also do not propagate to the updated agent packages. To retain these changes, you must use the JVM argument in Command Line as part of the startup script. For more information about using the JVM argument, see Use JVM Argument to Configure Bundle Properties.
Follow these steps:
  1. Go to the
    Packages
    tab in APM Command Center.
    APM Command Center shows a list of available packages.
    Next to each package name, you can see the number of active agents and total agents that the package is attached to.
  2. Select the package that you want to configure.
    Basic information for the package displays.
    The
    Versions
    section of the Configuration card shows the agent number and agent version that the package is attached to.
  3. Select
    Edit
    .
    The Agent Builder opens.
  4. (Optional) Change the agent package as needed. For more information, see Create Agent Packages.
  5. Select
    Next
    to move through the
    Select Bundles
    screen.
    The
    Configure Bundles
    tab opens. Here you can view all properties from the
    <AGENT_HOME>\core\config\IntroscopeAgent.profile
    file. You can add or disable extensions, add comments, and make other configuration changes. 
  6. Select
    the bundle that you want to configure. Information for the bundle displays.
    Filter the bundles by property name using the search function.
    • For each property, add a new value or select an option from the drop-down list where available.
      You can revert your changes by selecting the
      Settings
      icon and
      Reset
      from the drop-down list.
    • Add a new property by selecting
      Insert New
      from the
      Settings
      icon within an existing property.
      All updated or inserted properties show a user symbol to indicate that you made changes.
    • Delete properties by selecting the
      Settings
      icon next to each property and selecting
      Delete
      .
      You can only delete the properties that you added.
  7. Add a comment to describe the reason for your change.
  8. Select
    Next
    .
    The
    Install Instructions
    screen opens.
  9. Select the
    Pencil
    icon to add notes to the Installation Instructions, and select
    Done
    when you finish.
Import Bundles to APM Command Center
You can create your own custom bundles and can import them into APM Command Center. For more information about creating custom bundles, see Add Custom Bundles.
Follow these steps:
  1. In APM Command Center, go to the
    Bundles
    tab and select the
    Import
    button.
  2. Browse for the created or downloaded bundle and select
    Open
    .
    The bundle imports.
  3. View the bundle in the
    Bundles
    list.
  4. Go to the
    Packages
    tab, and add the bundle to the desired package. For more information about adding a bundle to a package, see Create Agent Packages.
Deploy the Agent Packages
You deploy agent packages from APM Command Center by downloading the package onto your application server. For all agents except the Java Agent, you must update the package manually when the monitored application is stopped. For more information about upgrading agents, see Manage Agent Packages and Bundles Using APM Command Center.
For Java Agents, you redeploy the new package to upgrade an agent to a new agent version or to apply changes to the bundles of running agents. You can also replace the entire agent package in APM Command Center. These changes take effect after you push them to an agent or after you restart the application server. All dynamic bundles and properties are marked with the dynamic icon in the APM Command Center
Bundles
tab. Non-dynamic bundles are marked with a restart icon in the
Bundles
tab. Bundles with the restart icon require that you restart the application server to apply the changes.
Follow these steps:
  1. In APM Command Center, select
    Packages
    .
    A list of available packages displays.
  2. Select the package that you want to deploy.
    APM Command Center shows basic information for the package.
    The
    Versions
    section of the Configuration card shows the agent number and agent version that the package is attached to.
  3. Select the
    Package URL
    .
    The agent package downloads.
  4. Copy the agent package to the target application server.
  5. Unzip the file, and copy the unzipped file to the application server.
  6. Follow the installation instructions in the
    Install Instructions
    card of the
    Packages
    tab.
  7. Restart the application server.
    The agent appears in the APM Command Center
    Agent
    tab after it connects to the application server.
Use the JVM Argument to Configure Bundle Properties in Command Line
You can use the JVM argument in a command-line command to configure the bundle property manually. You can also use this argument when you run the startup script for each agent package. Any changes that you make by using this method propagate to upgraded agent packages.
Example
Use
-D
before running the startup script.
-Dintroscope.agent.agentName=<name> -javaagent:c:\apache-tomcat-9.0.1\wily\Agent.jar