Deploy Agent Packages Using APM Command Center
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
bundleis 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.
- You can create a package to fit your target application environment, add and remove bundles, and configure the package to your needs in eitherDX APMor APM Command Center. For more information about usingDX APMto download an agent, see Configure and Download an Agent Package.
- You download the package as an archive file to install the agent. Refer to the installation instructions in the UI to install the agent.
- The agent then reports the package information in APM Command Center and the metrics in Application Performance Management.
- 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.
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
Previousto return to the previous screen.
Follow these steps:
- Go to thePackagestab in APM Command Center and selectNew.
- The Agent Builder opens.
- Enter aPackageNameandDescription.
- Select anOperating System Type(UNIX or Windows).
- Select aProcess. 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.
- If necessary, select theSecondary OS Name(AIX or Linux).
- Select anAgent Version.When you select theAgent 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.
- (Optional) If you want to specify the cloud proxy, add the cloud proxy address to theCloud Proxyfield. 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.
- SelectDoneto 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
Select Bundlestab of the Agent Builder, two columns list available and selected bundles:
- Available BundlesOptional bundles for special monitoring that are compatible with your environment.ExampleThe LeakHunter bundle
- Selected BundlesDefault, preselected bundles that are required or recommended for monitoring in your environment.ExampleThe Struts bundle for Tomcat.
The bundles that are listed in both columns are grouped according to their type:
- CoreCore monitoring components, such as the Java Agent binaries or APM Command Center extension.
- EnvironmentDepending on the platform, the Environment group contains bundles that monitor the application server.
- FeaturesVarious APM monitoring features to enhance metrics visibility.
- CustomUnofficial 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:
- Go to thePackagestab 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.
- Select the package that you want to configure.Basic information for the package displays.TheVersionssection of the Configuration card shows the agent number and agent version that the package is attached to.
- SelectEdit.The Agent Builder opens.
- To add or remove bundles and to change the bundle configuration, selectCustomize.TheSelect Bundlestab opens.
- Select the bundles appropriate for your monitoring needs, and selectAdd.Filter the bundles by property name using the search function.
- SelectDoneto save the bundles in the package.
Configure Bundle Properties and Installation Instructions in APM Command Center
You configure a bundle by editing current
IntroscopeAgent.profileproperties 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 system, 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:
- Go to thePackagestab 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.
- Select the package that you want to configure.Basic information for the package displays.TheVersionssection of the Configuration card shows the agent number and agent version that the package is attached to.As an administrator, you can set up an agent controller to connect through a proxy by filling out the following properties in the configuration page of the Agent Controller bundle:
Any undefined values will be taken from theagentManager.http.usernameproperty in the em-connection bundle.This feature only supports HTTP proxy.Troubleshooting:If an agent or controller cannot connect through a configured proxy, you can check:
If required, you can enable DEBUG logging level (introscope.agent.acc.controller.logging.level.com.ca.apm=DEBUG) inextensions/acc-controller-unix-*/bundle.propertiesto see the full content of HTTP communication.
- The proxy log files.
- On the controller side, the logs directory inside the agent.
- SelectEdit.The Agent Builder opens.
- (Optional) Change the agent package as needed. For more information, see Create Agent Packages.
- SelectNextto move through theSelect Bundlesscreen.TheConfigure Bundlestab opens. Here you can view all properties from the<AGENT_HOME>\core\config\IntroscopeAgent.profilefile. You can add or disable extensions, add comments, and make other configuration changes.
- SelectFilter 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 theSettingsicon andResetfrom the drop-down list.
- Add a new property by selectingInsert Newfrom theSettingsicon within an existing property.All updated or inserted properties show a user symbol to indicate that you made changes.
- Delete properties by selecting theSettingsicon next to each property and selectingDelete.You can only delete the properties that you added.
- Add a comment to describe the reason for your change.
- SelectNext.TheInstall Instructionsscreen opens.
- Select thePencilicon to add notes to the Installation Instructions, and selectDonewhen 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:
- In APM Command Center, go to theBundlestab and select theImportbutton.
- Browse for the created or downloaded bundle and selectOpen.The bundle imports.
- View the bundle in theBundleslist.
- Go to thePackagestab, 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
Bundlestab. Non-dynamic bundles are marked with a restart icon in the
Bundlestab. Bundles with the restart icon require that you restart the application server to apply the changes.
Follow these steps:
- In APM Command Center, selectPackages.A list of available packages displays.
- Select the package that you want to deploy.APM Command Center shows basic information for the package.TheVersionssection of the Configuration card shows the agent number and agent version that the package is attached to.
- Select thePackage URL.The agent package downloads.
- Copy the agent package to the target application server.
- Unzip the file, and copy the unzipped file to the application server.
- Follow the installation instructions in theInstall Instructionscard of thePackagestab.
- Restart the application server.The agent appears in the APM Command CenterAgenttab 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.
-Dbefore running the startup script.