Metric Schema Mapping (Telegraf)
Telegraf's metrics are auto-mapped to Oracle Management Cloud metrics.
Note:
Manual mapping of Telegraf metrics to Oracle Management Cloud metrics is not currently supported.The following table shows how Telegraf's metric schema is automatically mapped to Oracle Management Cloud's metric schema.
| Field | Value | Example |
|---|---|---|
| parentTargetType(64) | omc_target | omc_target |
| entityType(64) | '_gmc_telegraf_'<plugin> |
|
| typeDisplayName(128) | <Title cased plugin name, with underscores replaced by spaces> |
|
| entityName(256) |
<host tag value> or <host tag value>'-'<unique tag value> |
|
| metricGroupName(64) | <plugin> |
|
| metricGroupDisplayName(256) | <metricGroupName in title case with underscores replaced by spaces> |
|
| metricColumnName(64) | <field name> |
|
| metricColumnDisplayName(256) | <Title cased plugin name followed by a space followed by title cased field name, with underscores replaced by spaces> |
|
| metricColumnClass |
TS if the field name is "timestamp" or ends with "_ts"; STR if the field value is a string in the JSON sent by the http output plugin; NUM otherwise |
NUM |
You can extract the plugin, tags and field names by running the telegraf --test command.
Example
$ telegraf --test
2019/03/04 21:00:09 I! Using config file: /etc/telegraf/telegraf.conf
> cpu,collector=telegraf,cpu=cpu0,host=myhost.myco.com usage_guest=0,usage_guest_nice=0,usage_idle=100,usage_iowait=0,usage_irq=0,usage_nice=0,usage_softirq=0,usage_steal=0,usage_system=0,usage_user=0 1551762010000000000
> cpu,collector=telegraf,cpu=cpu1,host=myhost.myco.com usage_guest=0,usage_guest_nice=0,usage_idle=100,usage_iowait=0,usage_irq=0,usage_nice=0,usage_softirq=0,usage_steal=0,usage_system=0,usage_user=0 1551762010000000000
> cpu,collector=telegraf,cpu=cpu2,host=myhost.myco.com usage_guest=0,usage_guest_nice=0,usage_idle=98.00000004470348,usage_iowait=0,usage_irq=0,usage_nice=0,usage_softirq=0,usage_steal=0,usage_system=0,usage_user=1.999999998952262 1551762010000000000
> cpu,collector=telegraf,cpu=cpu3,host=myhost.myco.com usage_guest=0,usage_guest_nice=0,usage_idle=100,usage_iowait=0,usage_irq=0,usage_nice=0,usage_softirq=0,usage_steal=0,usage_system=0,usage_user=0 1551762010000000000
> cpu,collector=telegraf,cpu=cpu-total,host=myhost.myco.com usage_guest=0,usage_guest_nice=0,usage_idle=100,usage_iowait=0,usage_irq=0,usage_nice=0,usage_softirq=0,usage_steal=0,usage_system=0,usage_user=0 1551762010000000000
> mem,collector=telegraf,host=myhost.myco.com active=6735482880i,available=11130187776i,available_percent=73.67584678266645,buffered=3569352704i,cached=7279378432i,commit_limit=22233530368i,committed_as=4000460800i,dirty=839680i,free=281456640i,high_free=0i,high_total=0i,huge_page_size=2097152i,huge_pages_free=0i,huge_pages_total=0i,inactive=5336559616i,low_free=0i,low_total=0i,mapped=1415385088i,page_tables=116322304i,shared=1340026880i,slab=2446262272i,swap_cached=14417920i,swap_free=14367285248i,swap_total=14680047616i,total=15106969600i,used=3976781824i,used_percent=26.324153217333542,vmalloc_chunk=35184301154304i,vmalloc_total=35184372087808i,vmalloc_used=50819072i,wired=0i,write_back=0i,write_back_tmp=0i 1551762010000000000
The entity type is created based on the plugin, and field names in the data sent by Telegraf's HTTP output plugin. For entity naming, the value of the host tag is used primarily. In case the data contains fields that depend on additional information in the tag for uniqueness, such a unique tag value is automatically identified and appended to the entity name with a hyphen separator. You can override this behavior by adding a tag called entity_identifier to the input plugin. The entity_identifier tag specifies a custom tag that will be used to name the entity instances uniquely.
Example
...
# Read metrics about cpu usage
[[inputs.cpu]]
## Whether to report per-cpu stats or not
percpu = true
## Whether to report total system cpu stats or not
totalcpu = true
## If true, collect raw CPU time metrics.
collect_cpu_time = false
## If true, compute and report the sum of all non-idle CPU states.
# report_active = false
[inputs.cpu.tags]
entity_identifier = "cpu"
...Limitations
Here are some of the known limitations with metric schema mapping between Telegraf and Oracle Management Cloud:
- Field data specified in the input plugin must be uniquely identifiable using either one or two tags. That is, we require the data to be unique for each host (as resolved using the host tag's value) or made unique in combination with a single additional tag's value. For example, data from the procstat plugin which is configured by specifying a process name or pattern that can either match a single process or multiple processes. When it matches a single process, the resulting field data will contain a single PID record at a given timestamp and can be mapped uniquely in Oracle Management Cloud. When the match results in multiple processes, the resulting in field data with multiple PID records cannot currently be mapped to Oracle Management Cloud without data loss. For more information on this, see Troubleshooting Telegraf Metric Collection.
- The maximum number of fields per plugin that can be mapped to Oracle Management Cloud is 100. Mapping of Telegraf plugins with more than 100 fields to Oracle Management Cloud is not currently supported. For example data from Telegraf's nstat plugin (with over 100 fields) cannot be mapped to Oracle Management Cloud.
- Ingestion of aggregate metrics such as sum, min, max, mean, count, histograms, etc. from Telegraf into Oracle Management Cloud is currently not supported.
- Ingestion of metrics from plugins which emit multiple sets of fields and/or tags at a given timestamp, such as snmp and procstat is not currently supported.
- The maximum number of metric groups per entity type (auto-created by Oracle Management Cloud when using the automatic mapping) is 50. On the Telegraf side, this translates to 50 distinct plug-ins sending data to Oracle Management Cloud.