Widgets layout in APM v8 for custom agents (Agent Builder Agents)

Body

As you likely know, last versions of Agent Builder can generate custom agents that can be configured to connect APM v8.x servers, in addition
to the usual v6 infrastructure.

In order to enable a custom agent for APM v8, some additional steps are required, but they are all clearly documented in the Agent Builder manual
so we are not going to talk about it here in details.

One of these steps is about selecting the attribute groups you want to be showed in Dashboard widgets.

One of my customers was developing Agent Builder agents (AB version 6.3.5 Build id: 201707241506) to be used together with APM 8.1.4.
For a specific custom agent, he noticed that some widgets were truncated and so few attributes were not visible.
I made some test to understand the conditions leading to this unexpected behavior.
Most of the time you have two widgets on a single "line" of the dashboard.
This is fine if the widget shows data for a single row attribute group, because the size of these widgets perfectly fits the width of the browser panel.
I noticed that the truncated widgets always belong to multi-rows attribute groups.
So I created several custom agents that include multi rows and single rows attribute groups in different order.
And I noticed that the problem occurs only when the attribute groups are added in specific sequences.
Basically, if you add a single row attribute group and then two multi rows attribute groups, then again other two single row attribute groups,
the second multi rows attribute group widget is placed in the same "line" of the next single row attribute group widget and this causes the multi rows widget to be truncated.

Instead, if you create the custom agent with 2 single row attribute groups, 2 multi rows attribute groups and again 2 single rows attribute groups, they are all placed correctly because the multi rows widgets are placed as a single element in the dashboard line.

This is an example of a truncated widget:

This problem has been already discussed with Agent Builder development team and it is going to be fixed in next release of the tool.
But in the meantime, how can you avoid this ?

Please consider that the widgets are automatically added to the dashboard when custom agent is registered, we are not dealing with custom views.

The widgets are placed in the dashboard respecting the sequence of attribute groups listed in the Agent Builder tool.
You should add new attribute groups taking in mind this behavior.
A good idea would be to keep all the multi rows attribute groups as last elements in the dashboard, so you should add those attribute groups only after all
the others single row attribute groups have been already added.

If you don't want to put all the multi row widgets at the end, you must respect a specific sequence of single row and multi row attribute groups.
Just to give you some examples:

Good widget layout:
2 Single Row attribute groups
2 Multi Rows attribute groups
2 Single Row attribute groups

Truncated Widget layout:
1 Single Row attribute groups
2 Multi Rows attribute groups
1 Single Row attribute group

Truncated Widget layout:
1 Single Row attribute groups
2 Multi Rows attribute groups
2 Single Row attribute group

There might be other combinations leading to a bad layout, this is why my preferred option is to put the multi rows attribute groups after all the single row attribute groups.

This is a general rule that should be respected while creating a new custom agent for APM v8.
What to do if you have already created a custom agent that resulted in a truncated widget, and you don't want to create a agent from scratch to correct it ?

Agent Builder allows to "move" the position for the attribute groups previously added, and so as a consequence to alter the position of the related widget in the dashboard.

This is how you can do it :

1) Open Agent Builder tool and open the Agent project you want to modify
2) Click Dashboard

3) Click Dashboard Setup Wizard

4) A new wizard window will open, click next till arriving to "Attribute selection - Details". Right click the Agent node (in this case it is called OddWidgets) and select "Reorder Attribute Groups"

5) A new window will open, it shows the name of the attribute groups, in the right side of the panel you have the arrows to move up/down each single attribute group after having selected it.

In this specific case, Logical Disks and Processor_Information are multi-rows attribute groups; System, Memory and Server are single row attribute groups.
Following the suggestion above, I should move Logical Disks and Processor Information after System, Memory and Server, so that it looks like:

After you did this, you can click finish and then rebuild the agent, also changing the agent version.
Once you deployed the new custom agent to the target machine, it will connect to APM v8 and will send the updated jar file with the new widget configuration.
This will allow to correct the problem with truncated widgets.

I will keep this article updated with further information in case I have news about the official fix for the Agent Builder tool.

Hope it helps.

Subscribe and follow us for all the latest information directly on your social feeds: