Running the CF 2018 PMT? Have you manually applied the recent update to it?

March 8, 2019
ColdFusion troubleshooter
Wizard 33 posts
Followers: 35 people
2

Running the CF 2018 PMT? Have you manually applied the recent update to it?

ColdFusion troubleshooter
Wizard 33 posts
Followers: 35 people
March 8, 2019

It would be very easy to miss the fact that update 2 of CF2018 provided an update for the CF2018 Performance Monitoring Toolset, or PMT. But note that the PMT update is one that you must apply MANUALLY yourself. It’s not performed for you as part of running the CF update. And the new PMT update not only fixes some bugs, but it also adds some new features to the PMT.

This post helps you perform the update and understand better what’s new and changed in the PMT Update.

  • How would you know this PMT update exists?
  • Running the PMT update from the command line
  • Assessing how the PMT update went
  • How to uninstall the PMT update
  • What features are added by the PMT update
  • What are known issues even after the PMT Update

How would you know this PMT update exists?

You could be forgiven for missing the PMT update entirely. For one thing, there’s no mention of it at all in the CF2018 update 3 technote, and there’s only a brief one in the CF2018 update 2 technote. Let me explain.

Perhaps like many, you may have missed (or skipped or held out on) running CF2018 update 2 (from Feb 12) and you may just now be applying update 3 (from Mar 1). If so, then note that you won’t even SEE mention of the PMT update in the technote for CF2018 update 3. Then again, that update 3 wasn’t technically when the PMT update was provided. That was in update 2 (see below).

Sidebar: But note that you also won’t see mention of the many other improvements added to CF2018 with update 2. Instead, like all CF update technotes, they leave you to “know” to go back and look at previous update technotes, to see what the previous update offers. I plan to do another post soon to highlight that for folks, as it’s of course a bigger issue than just this PMT update.)

But if you DO look at the technote for CF2018 update 2, you will find this brief mention of the PMT:

Updates to Performance Monitoring Toolset. When you install Update 2, the Performance Monitoring Toolset Hotfix also gets downloaded. The Hotfix is located in [CF_HOME]cfusionhf-updateshf-2018-00002-313919PMT-hotfix.

Here again, you could be forgiven for not only missing it, but missing the significance of that it’s trying to convey. Let’s consider a few things that sentence does and doesn’t tell us:

  1. Note that the link offered is NOT a link to info about the PMT (as you might presume from the words used in the link, and like I offered in the opening paragraph above). Instead it is a link to a technote ABOUT the PMT update
  2. Note that the link (and the doc it links to) refers to the PMT update as “update 1”. So to be clear, CF2018 Update 2 introduced this CF2018 PMT Update 1. It makes sense, but since PMT updates are a new thing, I just want to draw attention to this distinction
  3. Note that the text tells us WHERE “the hotfix is located”, but it does NOT tell us [a] THAT the update is a jar (java archive) file, nor [b] THAT it’s not automatically applied by the CF update, nor [c] WHAT we are to do with that info. But I will tell you in a moment
    • Beware also: if you applied update 3, then the folder above would instead be hf-updateshf-2018-00003-314033PMT-hotfix
  4. Finally, note that the text doesn’t convey anything about what is fixed nor that there is anything new, related to the PMT with this update. You would find that in the release note it points to, but I will share more, below

So, now we now there IS a PMT update, and we have a sense of where it is and that we need to do something with it. Let me explain that, and then we will move on to highlighting what’s new and fixed in the PMT update.

Running the PMT update from the command line

So I said at the opening that the CF update doesn’t perform the PMT update, and that is true. But note that the CF update DOES actually put the needed update jar file into place, within the folders of the CF update itself.

But then YOU must either run that jar (if the PMT is on the same machine) or copy that jar to the machine where you do have the PMT running, and run it there. (The PMT is not only designed to run on a server separate from the CF instance/s it is monitoring, but it is generally recommended that you run it separately, as the PMT can be a resource-intensive tool itself.)

Since the PMT update is a jar file, we need to execute it using Java. And for most folks, you will want to run that from the command line.

First, we need to take note of the locations for the PMT and CF installation directories. Follow these steps:

  1. Go to wherever the PMT is installed (whatever machine) and take note of the path where the PMT is installed:
    • For a typical Windows installation, it might be simply: C:ColdFusion2018PerformanceMonitoringToolset
  2. Go to wherever CF2018 is installed (and has update 2 or above installed), and take note of the location of the PMT update jar. As indicated the technote as quoted above, it’s in the hotfix updates (hf-updates) folder for the update you applied:
    • In a typical Windows install, having run CF2018 update 3, that would be C:ColdFusion2018cfusionhf-updateshf-2018-00003-314033PMT-hotfix
  3. Finally, if the PMT is installed on a machine separate from CF, copy that jar (the name will be simply hotfix.jar to the server where the PMT is installed.
    • You can put it into any folder. The root of the PMT folder itself should be a safe place.

Second, we want to run java from the command line, to execute that jar. And the easiest way to do that is using the Java executable that is itself implemented within the PMT:

  1. Open a command prompt (on that machine running the PMT), and run that “as admin” if on Windows
    • Discussing how to open the command prompt on Windows or Linux, and how to open the command “as admin” is beyond the scope of this blog post. You should be able to find sufficient information via web searching, or find someone with such experience to help
  2. Run the java executable as located within the PMT against the hotfix.jar file

Some readers may be wondering, “Do I really need to go through the bother of opening the command prompt and running the jar that way? Can’t I just click on it to run it?” And the fact is that you may well be able to click on a jar and run it. It depends on whether you have a “public jre” on your server, meaning (among other things) that the java executable is in your system “path”. There are two possible problems with “just double-clicking the jar”. First, it may or may not be the same Java version that your PMT is running. Second, that will not run the jar “as admin”, which may lead to problems in some cases on Windows. So it’s safest to proceed with the command-line install of the update.

Here is the command for a typical Windows install, assuming both CF and the PMT are on the same machine. I have bolded the key elements (running java, with the -jar argument, naming the jar to be executed). The other elements may vary for you depending on file locations and operating system:

C:ColdFusion2018PerformanceMonitoringToolsetjrebinjava.exe -jar C:ColdFusion2018cfusionhf-updateshf-2018-00003-314033PMT-hotfixhotfix.jar

And if the PMT is on its own machine, but you have copied the hotfix.jar to the root of the PMT folder on that machine, the following is an example command to run:

C:ColdFusion2018PerformanceMonitoringToolsetjrebinjava.exe -jar C:ColdFusion2018PerformanceMonitoringToolsetPMT-hotfixhotfix.jar

If all is well, this would begin prompting you to proceed with the PMT update.

Before you let it get beyond the first prompt, though, you may want to consider stopping the PMT services yourself. Sure, the PMT update should stop your PMT services (the PMT and the PMT datastore), but it may not. You may want to do that yourself, as a precaution. The name (“display names”) of the services are “ColdFusion 2018 Performance Monitoring Toolset” and “ColdFusion 2018 Performance Monitoring Toolset Datastore Service”, respectively (though note that technically the “service name” of the datastore service is “elasticsearch-service-x64”, if you may be stopping it from the command line.)

Anyway, back to the installer, as it proceeds through its prompts, note that one of the prompts will ask where the PMT is installed. It will presume to know where it’s installed (in the case of Windows, on the C drive), so note that you may need to tell it where YOU have installed the PMT, as we discovered above. It won’t let you proceed until you tell it the location where the PMT is installed.

(Some may know that the CF updates themselves are also downloaded as jar files, but since the CF Admin offers a UI for applying them, you may never notice that. And note that this same option to run the jar from the command line is an option–even sometimes a preferred method–for running the CF updates. Again, that’s beyond the scope of this post.)

Assessing how the PMT update went

Assuming all goes will with the update, it will soon report that it is starting the PMT services, and if you then visit the url for the PMT, you should see it prompting you to login.

But you may get an error during the installer. For instance, it’s not uncommon in my experience for you to get an error at the end of the PMT update installer reporting:

Unable to start Performance Monitoring Toolset

Cannot start Performance Monitoring Toolset. Check if the Datastore is up and running

You might naturally panic at the sight of this, but not to worry. Just proceed past that prompt. You may even see the next prompt reporting “congratulations”, and that the update was “successfully installed”. Close that prompt, and just go start the services for the PMT datastore and then the PMT itself (I shared the names above). It just seems to be perhaps a timing issue.

Always check the update logs

Before you move on (whether there is a seeming problem or not), note that there is a log for the update. (The log won’t be written until you completely finish the update, closing any remaining prompts.)

It’s always wise to look at that update log, to confirm there were no errors. The PMT update install log would be found within the PMT folder in a newly available hf-updates (for the PMT, not to be confused with the hf-updates for the CF installation folder). In a typical Windows install, the install log would be found at D:ColdFusion2018PerformanceMonitoringToolsethf-updateshf-2018-00001-313919, and the install log might have a name like Adobe_ColdFusion_2018_Performance_Monitoring_Toolset__Update_1_Install_03_07_2019_23_16_02.log. Open that and look for a table (close to the top than the bottom) headed “Summary”, and reporting a count of Successes and Errors. You want all successes.

(I did blog post recently (here on the CF portal) talking about how and why to check that same sort of update install log after any CF update, as well. While the location to look in will be different, the discussion of what to look for and how to respond to problems will be substantially similar. See Having problems after applying a CF update? What to check first!)

And note that there are also logs for the PMT and the PMT Datastore services themselves (in the log and datastore/logs folders of the PMT directory.)

If you really get stuck with the install of the update, note that you can reach out for help from the Adobe CF team, who offer an email address for installation problems, called cfinstal@adobe.com. (Yes, that really is just one “L”.) Or I am available on a consulting basis for remote, short-term assistance, with satisfaction guaranteed.

How to uninstall the PMT update

While you shouldn’t need to do it, note that you CAN uninstall the PMT update. To do so, you would just use the information and command-line examples above, but instead point to the uninstaller.jar file found in the C:ColdFusion2018PerformanceMonitoringToolsethf-updateshf-2018-00001-313919uninstall folder.

And note that after uninstalling, there is an uninstall log in the same HF-Updates location for the PMT Update 1, as discussed above. you should always check that also to make sure there are 0 errors.

What features are added by the PMT update

Assuming all goes well with the update, you may wonder, “what was all that bother for?” 🙂 I hinted above that there were both new PMT features and PMT bug fixes. Let’s look at the new features first. And there are two places that you can see a discussion of what was new in the PMT update.

First, PMT update 1 technote I pointed to before does list a few new items (and note that it offers a link to more info on each new/changed feature):

  • Support for HTTPS/SSL (you can now access Performance Monitoring Toolset dashboard over secured HTTPS/SSL)
  • Tree view of Code Profiler data (you can see the results of a Code Profiler in the form of a tree-like structure in ColdFusion Builder)
  • Datastore health monitor (you can set alerts and check Datastore health, if any parameter goes beyond a defined threshold)
  • Change theme (you can switch between a dark and a light theme)
  • Most frequently run queries (you can see a graph of most frequently run queries and check SQL statistics for the queries
  • View tracked and un-tracked servers (you can view both tracked and un-tracked servers in the Topology section)

Check out the links offered on that update technote page, for more on each of those.

FWIW, I’ll point out that there is yet another place that lists these new features in the PMT per its update: did you know there is actually a “release notes” page for each CF version, and it’s updated for each update that adds new features, and that also happens to lists the new features per the PMT update offered in that CF 2018 Update 2. What I’m referring to is the section on update 2 in the cf2018 update “release notes”, which is pointed to from the CF 2018 Update 2 technote.

Sidebar: many people don’t realize/notice there even IS a release notes document for the updates of each release. That’s a topic for another blog post I plan. Again note that not EVERY update has a section in the notes for that release, since some updates may just add a bug or security fix, having no related feature change.

What are known issues even after the PMT Update

Finally, even after applying the PMT update, there are still a few “known issues”. These are discussed in the PMT update 1 technote ,”known issues” section. See that for more, but briefly, the issues relate to:

  • How the PMT will fail to start if, after installing it, you point it to use Java 11, and how to fix that
  • How if you need to change the PMT username/password, you must uninstall the PMT update, change the password, and then re-install the update
  • An issue related to SUSE Linux and the username used to run the PMT
  • REST data does not get captured for a J2EE node in Performance Monitoring Toolset
  • An issue when connecting a J2EE server that is running a node on SSL

So, lots to say and know about the PMT update. Who knew, right? Well, now you do!

Comments (2)
2019-03-09 14:52:29
2019-03-09 14:52:29

The Performance Monitoring Toolset has a refreshed installer available here from February 2019:

https://www.adobe.com/support/coldfusion/downloads.html

I don’t know if this includes PMT Update 1 or not. Note that if you go to the main download link for CF 2018 (http://www.adobe.com/go/trycoldfusion) it still offers the old PMT installer.

Like
2019-03-09 13:18:40
2019-03-09 13:18:40

Thank you for the detailed post Charlie! I just applied the update.

Like
Add your comment