Tag, You’re It!: Mastering ESM Tags

Enterprise Session Monitor Tags are annotations that appear on the Enterprise Session Monitor time-series graph when they occur. This seemingly simple concept can be quite powerful for the developer or the administrator in understanding what’s happening in each session. The purpose of this post is to explore these tags in SAS Enterprise Session Monitor. New to Enterprise Session Monitor? Catch my earlier posts on the topic here: Obsessing Over Observability and Taking Control: Custom Process Monitoring with filterSpec in Enterprise Session Monitor.

Program tagging is performed with the %esmtag() macro, which is defined by SAS Enterprise Session Monitor. Tags are available in all systems monitored by SAS Enterprise Session Monitor: SAS 9, SAS Viya 3.5, and SAS Viya 4. In order to enable program tagging in SAS Viya, here are the steps that need to be taken: SAS Enterprise Session Monitor: Enable Program Tagging.

These user-generated annotations function similarly to the %PUT statement, allowing for a developer to leave comments or notes for themselves in the SAS program log. With tagging, this is taken a step further -- instead of only printing output to the SAS log, a labeled flag appears on the time-series graph in the Live View and Timespans View of SAS Enterprise Session Monitor. So, when they are observing the session, they can see these markers. They can be used for marking the start or end of code submission, the beginning of various sections of program code, and much more.

Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.

Tags are used to provide extra information to people who are administrating, monitoring, or developing for SAS platforms. Tagging adds additional, meaningful context to understand what is occurring inside these sessions without needing to go and read the log of every single program execution. They can also be inserted into autoexec files or supplied with custom pre- or post- code.

I’ve gotten a few paragraphs in and haven’t mentioned syntax yet, so I probably should. Once program tagging has been enabled, tags can be written to SAS Enterprise session monitor by calling the %esmtag() macro. The macro accepts up to three parameters: the flag label, text to appear on mouse hover, and the Hex color code for the flag.

%esmtag(flag text, text on hover, #BBBBBB);

Tags also accept some basic HTML markup for line breaks and text formatting:

%esmtag(flag text, 
      <b>This text is bold</b><br>
      <i>This text is italic</i><br>
      <small>This is some smaller text.</small><br>
      This is <sub>subscripted</sub> text.<br>
      This is <sup>superscripted</sup> text.
   );

This is where things begin to get interesting, as tags can also accept macro variables. With macro variables, tags can display dynamic information to the time series graph, not only static text strings.

Some ideas for tag use include displaying a user’s name when they submit a program for execution. A string like this can be added to custom code within SAS Studio:

This is probably pretty cool on reusable compute servers.

%esmtag(start,<b>&sysuserid</b> is starting code submission.);

You can also use macro variables to display the number of observations in a table after a DATA step completes.

Phew, that's a lot of rows.

proc sql noprint;
   select count(*) into :obs_count from eriktable;
   quit;
%esmtag(&syslast has <b>&obs_count</b> obs.)

What about that last parameter on the &esmtag() macro? The third parameter sets the color of the flag. Let’s add some interesting colors based on the output. This is a spin on one of the more complex tagging examples from documentation.

Pretend we’re working with some variable data that might fall below a specific threshold. We can use an IF-THEN-ELSE-IF statement to build several different tags, one for low, medium, or expected numbers of observations. Within this code, each tag dynamically adjusts its color—red, yellow, or green—based on the number of observations generated in the table. This dynamic approach enhances both readability and visual appeal. While this example deals with rows of table data, this same concept is transferable for other uses. I’d love to see what kinds of interesting tags administrators or developers create.

These tags change their color based on the number of observations generated in the preceding table.

proc sql;
   create table eriktable as
      select *
      from sashelp.cars;
   quit;

data _null_;
   set eriktable end=final;
   if final then
      do;
         if &sqlobs. >= 300 then
            call execute('%esmtag(Good Number of Rows (&sqlobs.),, #AAFFAA);'); /* Green */
         else if 99 <= &sqlobs. <= 299 then
            call execute('%esmtag(Medium Number of Rows (&sqlobs.),, #FFD324);'); /* Yellow */
         else
            call execute('%esmtag(Low Number of Rows (&sqlobs.),, #DDAAAA);'); /* Red */
      end;
run;

Once these tags have passed by in the time series graph, they are not gone. You can search for them in the Events and Logs page of SAS Enterprise Session Monitor. This way, these meaningful events are valuable information and is retained for future reference.

Thank you for reading. Ready to learn more about SAS Enterprise Session Manager? Here are some additional resources to explore:

Observability Solutions for the SAS Viya Platform

SAS Enterprise Session Monitor – Deployment Using Ansible

Course: System Tuning Using SAS® Enterprise Session Monitor

Find more articles from SAS Global Enablement and Learning here.

SAS Communities Library