Skip to content

Commit 87b1861

Browse files
jacomagojacomago
committed
Update documentation for metrics
1 parent ed34567 commit 87b1861

File tree

5 files changed

+141
-112
lines changed

5 files changed

+141
-112
lines changed

‎src/main/java/org/phoebus/channelfinder/MetricsService.java‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -143,7 +143,11 @@ private List<Tag> metricTagsFromMultiValueMap(MultiValueMap<String, String> mult
143143
List<Tag> metricTags = new ArrayList<>();
144144
for (Map.Entry<String, String> entry : multiValueMap.toSingleValueMap().entrySet()) {
145145
if (entry.getKey().endsWith(NEGATE)) {
146-
metricTags.add(new ImmutableTag(entry.getKey().substring(0, entry.getKey().length() - 1), NOT_SET));
146+
if (entry.getValue().equals("*")) {
147+
metricTags.add(new ImmutableTag(entry.getKey().substring(0, entry.getKey().length() - 1), NOT_SET));
148+
} else {
149+
metricTags.add(new ImmutableTag(entry.getKey().substring(0, entry.getKey().length() - 1), NEGATE + entry.getValue()));
150+
}
147151
} else {
148152
metricTags.add(new ImmutableTag(entry.getKey(), entry.getValue()));
149153
}

‎src/site/sphinx/aa_processor.rst‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
.. _aa_processor:
2+
Archiver Appliance Processor
3+
============================
4+
5+
.. _aa_processor_config:
6+
Configuration
7+
-------------
8+
To enable the archiver appliance configuration processor, set the property :ref:`aa.enabled` to **true**.
9+
10+
A list of archiver appliance URLs and aliases. ::
11+
12+
aa.urls={'default': 'http://archiver-01.example.com:17665', 'neutron-controls': 'http://archiver-02.example.com:17665'}
13+
14+
To set the choice of default archiver appliance, set the property :ref:`aa.default_alias` to the alias of the default archiver appliance. This setting can also be a comma-separated list if you want multiple default archivers.
15+
16+
To pass the PV as "pva://PVNAME" to the archiver appliance, set the property :ref:`aa.pva` to **true**.
17+
18+
The properties checked for setting a PV to be archived are ::
19+
20+
aa.archive_property_name=archive
21+
aa.archiver_property_name=archiver
22+
23+
To set the auto pause behaviour, configure the parameter :ref:`aa.auto_pause`. Set to pvStatus to pause on pvStatus=Inactive,
24+
and resume on pvStatus=Active. Set to archive to pause on archive_property_name not existing. Set to both to pause on pvStatus=Inactive and archive_property_name::
25+
26+
aa.auto_pause=pvStatus,archive
27+
28+
AA Plugin Example
29+
-----------------
30+
31+
A common use case for the archiver appliance processor is for sites that use the Recsync project to populate Channel Finder.
32+
With the reccaster module, info tags in the IOC database specify the archiving parameters and these properties will be pushed to Channel Finder by the recceiver service.
33+
34+
In the example database below, the AA plugin will make requests to archive each PV.
35+
The plugin will request MyPV to be archived with the SCAN method and sampling rate of 10 seconds to the "aa_appliance0" instance specified in aa.urls property.
36+
MyPV2 will use the MONITOR method and a sampling rate of 0.1 seconds, and the request will be sent to the URL mapped to the the "aa_appliance1: key.
37+
MyPolicyPV shows an example that uses an archiver appliance "Named Policy" string and also uses the URL specified in the aa.default_alias property since the "archiver" tag is missing.
38+
39+
For named policy PVs, the AA plugin will first check that the named policy exists in the appliance using the getPolicyList BPL endpoint.
40+
41+
.. code-block::
42+
43+
record(ao, "MyPV") {
44+
info(archive, "scan@10")
45+
info(archiver, "aa_appliance0")
46+
}
47+
record(ao, "MyPV2") {
48+
info(archive, "[email protected]")
49+
info(archiver, "aa_appliance1")
50+
}
51+
record(ao, "MyPVWithMultipleArchivers") {
52+
info(archive, "[email protected]")
53+
info(archiver, "aa_appliance0,aa_appliance1")
54+
}
55+
record(ao, "MyPolicyPV") {
56+
info(archive, "AAPolicyName")
57+
# no archiver tag so PV sent to archiver in aa.default_alias
58+
}

‎src/site/sphinx/config.rst‎

Lines changed: 3 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -91,124 +91,16 @@ SSL Config
9191

9292
server.ssl.key-store - Path to SSL keystore file
9393

94-
Archiver Appliance Configuration Processor
94+
Archiver Appliance Processor Configuration
9595
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
96-
To enable the archiver appliance configuration processor, set the property :ref:`aa.enabled` to **true**.
9796

98-
A list of archiver appliance URLs and aliases. ::
99-
100-
aa.urls={'default': 'http://archiver-01.example.com:17665', 'neutron-controls': 'http://archiver-02.example.com:17665'}
101-
102-
To set the choice of default archiver appliance, set the property :ref:`aa.default_alias` to the alias of the default archiver appliance. This setting can also be a comma-separated list if you want multiple default archivers.
103-
104-
To pass the PV as "pva://PVNAME" to the archiver appliance, set the property :ref:`aa.pva` to **true**.
105-
106-
The properties checked for setting a PV to be archived are ::
107-
108-
aa.archive_property_name=archive
109-
aa.archiver_property_name=archiver
110-
111-
To set the auto pause behaviour, configure the parameter :ref:`aa.auto_pause`. Set to pvStatus to pause on pvStatus=Inactive,
112-
and resume on pvStatus=Active. Set to archive to pause on archive_property_name not existing. Set to both to pause on pvStatus=Inactive and archive_property_name::
113-
114-
aa.auto_pause=pvStatus,archive
115-
116-
AA Plugin Example
117-
"""""""""""""""""
118-
119-
A common use case for the archiver appliance processor is for sites that use the Recsync project to populate Channel Finder.
120-
With the reccaster module, info tags in the IOC database specify the archiving parameters and these properties will be pushed to Channel Finder by the recceiver service.
121-
122-
In the example database below, the AA plugin will make requests to archive each PV.
123-
The plugin will request MyPV to be archived with the SCAN method and sampling rate of 10 seconds to the "aa_appliance0" instance specified in aa.urls property.
124-
MyPV2 will use the MONITOR method and a sampling rate of 0.1 seconds, and the request will be sent to the URL mapped to the the "aa_appliance1: key.
125-
MyPolicyPV shows an example that uses an archiver appliance "Named Policy" string and also uses the URL specified in the aa.default_alias property since the "archiver" tag is missing.
126-
127-
For named policy PVs, the AA plugin will first check that the named policy exists in the appliance using the getPolicyList BPL endpoint.
128-
129-
.. code-block::
130-
131-
record(ao, "MyPV") {
132-
info(archive, "scan@10")
133-
info(archiver, "aa_appliance0")
134-
}
135-
record(ao, "MyPV2") {
136-
info(archive, "[email protected]")
137-
info(archiver, "aa_appliance1")
138-
}
139-
record(ao, "MyPVWithMultipleArchivers") {
140-
info(archive, "[email protected]")
141-
info(archiver, "aa_appliance0,aa_appliance1")
142-
}
143-
record(ao, "MyPolicyPV") {
144-
info(archive, "AAPolicyName")
145-
# no archiver tag so PV sent to archiver in aa.default_alias
146-
}
97+
See :ref:`_aa_processor_config`.
14798

14899
Metrics
149100
^^^^^^^
150101

151-
Metrics can be exposed by setting the `management.endpoints.web.exposure.include=prometheus` property.
152-
153-
.. code-block::
154-
155-
management.endpoints.web.exposure.include=prometheus, metrics, health, info
156-
157-
Adding the prometheus property will expose the prometheus endpoint which can be scraped by prometheus.
158-
159-
The default metrics exposed by specifying "metrics" are:
160-
161-
.. code-block::
162-
163-
cf.total.channel.count - Count of all ChannelFinder channels
164-
cf.property.count - Count of all Property Names
165-
cf.tag.count - Count of all tags
166-
167-
Tag Metrics
168-
"""""""""""
169-
170-
You can also set the metrics.tags to add counts of number of channels per tag. These are exposed as
171-
`cf.tag_on_channels.count{tag=tagName}`. For example
172-
173-
.. code-block::
174-
175-
metrics.tags=Accelerator, Beamline1, Beamline2, Beamline3
176-
177-
Would produce metrics:
178-
179-
.. code-block::
180-
181-
cf.tag_on_channels.count=109
182-
cf.tag_on_channels.count{tag=Accelerator} = 100
183-
cf.tag_on_channels.count{tag=Beamline1} = 3
184-
cf.tag_on_channels.count{tag=Beamline2} = 3
185-
cf.tag_on_channels.count{tag=Beamline3} = 3
186-
187-
Property Metrics
188-
""""""""""""""""
189-
190-
You can also set the metrics.properties to add counts of number of channels per property and value. These are exposed as
191-
`cf_propertyName_channels_count{propertyName=propertyValue}`. For example:
192-
193-
194-
.. code-block::
195-
196-
metrics.properties=pvStatus:Active, Inactive; archive: default, fast, slow; archiver: aa_beamline, aa_acccelerator
197-
198-
Would produce metrics:
199-
200-
.. code-block::
102+
See :ref:`_metrics`.
201103

202-
cf.pvStatus.channel.count=100
203-
cf.pvStatus.channel.count{pvStatus=Active}=50
204-
cf.pvStatus.channel.count{pvStatus=Active}=50
205-
cf.archive.channel.count=21
206-
cf.archive.channel.count{archive=default}=1
207-
cf.archive.channel.count{archive=fast}=10
208-
cf.archive.channel.count{archive=slow}=10
209-
cf.archiver.channel.count=20
210-
cf.archive.channel.count{archive=aa_beamline}=10
211-
cf.archive.channel.count{archive=aa_acccelerator}=10
212104

213105
EPICS PV Access Server
214106
----------------------

‎src/site/sphinx/index.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,3 +22,5 @@ Related projects may be found in the `ChannelFinder <https://github.com/ChannelF
2222
overview
2323
config
2424
api
25+
metrics
26+
aa_processor

‎src/site/sphinx/metrics.rst‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
.. _metrics:
2+
Metrics
3+
=======
4+
5+
Metrics can be exposed by setting the `management.endpoints.web.exposure.include=prometheus` property.
6+
7+
.. code-block::
8+
9+
management.endpoints.web.exposure.include=prometheus, metrics, health, info
10+
11+
Adding the prometheus property will expose the prometheus endpoint which can be scraped by prometheus.
12+
13+
The default metrics exposed by specifying "metrics" are:
14+
15+
.. code-block::
16+
17+
cf.total.channel.count - Count of all ChannelFinder channels
18+
cf.property.count - Count of all Property Names
19+
cf.tag.count - Count of all tags
20+
21+
Tag Metrics
22+
-----------
23+
24+
You can also set the metrics.tags to add counts of number of channels per tag. These are exposed as
25+
`cf.tag_on_channels.count{tag=tagName}`. For example
26+
27+
.. code-block::
28+
29+
metrics.tags=Accelerator, Beamline1, Beamline2, Beamline3
30+
31+
Would produce metrics:
32+
33+
.. code-block::
34+
35+
cf.tag_on_channels.count=109
36+
cf.tag_on_channels.count{tag=Accelerator} = 100
37+
cf.tag_on_channels.count{tag=Beamline1} = 3
38+
cf.tag_on_channels.count{tag=Beamline2} = 3
39+
cf.tag_on_channels.count{tag=Beamline3} = 3
40+
41+
Property Metrics
42+
----------------
43+
44+
You can also set the metrics.properties to add counts of number of channels per property and value. These are exposed as
45+
`cf_channels_count{prop0=propValueA, prop1=propValueB}`. For example:
46+
47+
48+
.. code-block::
49+
50+
metrics.properties=pvStatus:Active, Inactive; archive: default, !*; archiver: beam, acc, !*
51+
52+
Would produce metrics:
53+
54+
.. code-block::
55+
56+
cf_channel_count{archive="-",archiver="beam",pvStatus="Inactive",} 0.0
57+
cf_channel_count{archive="default",archiver="beam",pvStatus="Inactive",} 0.0
58+
cf_channel_count{archive="-",archiver="beam",pvStatus="Active",} 0.0
59+
cf_channel_count{archive="-",archiver="-",pvStatus="Active",} 2.0
60+
cf_channel_count{archive="default",archiver="acc",pvStatus="Inactive",} 0.0
61+
cf_channel_count{archive="-",archiver="acc",pvStatus="Active",} 0.0
62+
cf_channel_count{archive="default",archiver="-",pvStatus="Inactive",} 0.0
63+
cf_channel_count{archive="default",archiver="-",pvStatus="Active",} 0.0
64+
cf_channel_count{archive="default",archiver="beam",pvStatus="Active",} 0.0
65+
cf_channel_count{archive="-",archiver="acc",pvStatus="Inactive",} 0.0
66+
cf_channel_count{archive="-",archiver="-",pvStatus="Inactive",} 1.0
67+
cf_channel_count{archive="default",archiver="acc",pvStatus="Active",} 0.0
68+
69+
Here you can see the value "!*" is special, it does a negation on property name. So for a property name "a", using the
70+
property value "!*" provides the count of all the channels where the property does not exist.
71+
72+
Note that "!someValue" is also special in that it will search for all the channels where the property is set to
73+
something other than "someValue".

0 commit comments

Comments
 (0)