VMware

Log Insight 4.0: vSphere Datastore ID to Name Aliasing

by Steve Flanders

The Log Insight team takes customer experience seriously. As you know, there is a public community where you can submit and vote for features requests. The number one feature was vSphere datastore ID to name aliasing. I am happy to announce it has been implemented in Log Insight 4.0. Read on to learn more!
li-logo

The Problem

Here is the problem that was reported: vSphere logs datastore IDs (e.g. naa.*) that are not user-friendly. These same datastores have user-friendly names. Log Insight should have the ability to display these user-friendly names. This would make troubleshooting easier.

Seems reasonable to me!

How to Implement

The next question becomes how to implement the solution? A few possibilities existed:

  1. Leverage vROps integration. vROps knows this information so arguably Log Insight could poll vROps like it does for inventory mapping today.
  2. Call vSphere directly. vSphere obviously knows this information so arguably Log Insight could poll the vSphere inventory.
  3. Leverage logs already being consumed by Log Insight. If both the datastore ID and user-friendly name existed in the logs and they could be correlated to one another then a mapping could be created.

As I am sure you know, there are pros and cons to each approach. So what was implemented?

The Solution

It turns out at least one log message does exist that contains both the datastore ID and the user-friendly name — in all supported versions of vSphere. This means that option three could be used and since it provided the most flexibility, it was chosen. When designing the feature, some additional considerations were taken into account:

  • It would be nice to support both static and dynamic aliasing
  • Ideally alias fields should behave like all other types of fields
  • Ideally the ability to define aliases should be exposed to the user
  • Defining complex aliases (e.g. across multiple events) may be necessary

Where aliases are defined

In content packs! That is right, the feature was designed with future flexibility in mind. Today, all of the available aliases are defined in the VMware – vSphere version 4.0 content pack. If you open the content pack, you will see two different types of aliasing:

  1. aliasFields = static mapping of a value to a key for a given searchField
    • name = name of the alias field
    • searchField = name of the field for which an alias is desired
    • value = value of the searchField to match
    • key = alias to display with events that contain the searchField
    • definition = 
        "aliasFields":[{
     "name":"vmw_esxi_scsi_host_status",
     "searchField":"vmw_esxi_scsi_host_status_label",
     "aliases":[{
        "key":"OK",          "value":"0x0"},{
        "key":"NO_CONNECT",  "value":"0x1"},{
        "key":"BUS_BUSY",    "value":"0x2"},{
        "key":"TIME_OUT",    "value":"0x3"},{
        "key":"BAD_TARGET",  "value":"0x4"},{
        "key":"ABORT",       "value":"0x5"},{
        "key":"PARITY",      "value":"0x6"},{
        "key":"ERROR",       "value":"0x7"},{
        "key":"RESET",       "value":"0x8"},{
        "key":"BAD_INTR",    "value":"0x9"},{
        "key":"PASSTHROUGH", "value":"0xa"},{
        "key":"SOFT_ERROR",  "value":"0xb"
     }]
  },{
    "name":"vmw_esxi_scsi_device_status",
    "searchField":"vmw_esxi_scsi_device_status_label",
    "aliases":[{
       "key":"GOOD",                 "value":"0x0"},{
       "key":"CHECK CONDITION",      "value":"0x2"},{
       "key":"CONDITION MET",        "value":"0x4"},{
       "key":"BUSY",                 "value":"0x8"},{
       "key":"RESERVATION CONFLICT", "value":"0x18"},{
       "key":"TASK SET FULL",        "value":"0x28"},{
       "key":"ACA ACTIVE",           "value":"0x30"},{
       "key":"TASK ABORTED",         "value":"0x40"
    }]
  },{
    "name":"vmw_esxi_scsi_sense_code",
    "searchField":"vmw_esxi_scsi_sense_label",
    "aliases":[{
       "key":"NO SENSE",        "value":"0x0"},{
       "key":"RECOVERED ERROR", "value":"0x1"},{
       "key":"NOT READY",       "value":"0x2"},{
       "key":"MEDIUM ERROR",    "value":"0x3"},{
       "key":"HARDWARE ERROR",  "value":"0x4"},{
       "key":"ILLEGAL REQUEST", "value":"0x5"},{
       "key":"UNIT ATTENTION",  "value":"0x6"},{
       "key":"DATA PROTECT",    "value":"0x7"},{
       "key":"BLANK CHECK",     "value":"0x8"},{
       "key":"VENDOR SPECIFIC", "value":"0x9"},{
       "key":"COPY ABORTED",    "value":"0xA"},{
       "key":"ABORTED COMMAND", "value":"0xB"},{
       "key":"VOLUME OVERFLOW", "value":"0xD"},{
       "key":"MISCOMPARE",      "value":"0xE"
    }]
  }],
    • example =
      event:
      aliases:
  2. aliasRules = dynamic mapping of a valueField to a keyField for associatedFields
    • name = unique name to identity the alias (internal only)
    • filter = keywords and/or globs to find the event with the key and value fields (more specific the better)
    • keyField = the field for which a dynamic alias should be mapped against
    • valueField = a second field in the same event as the keyField that provides the alias value
    • aliasFieldName = name of the alias field to be shown next to events that contain the keyField
    • associatedFields = the field(s) for which the aliasFieldName should appear
    • definition = 
        "aliasRules":[{
    "name":"DatastoreFromVmFileSystem",
    "filter":"hostd VmFileSystem Label headExtent naa*",
    "keyField":"vmw_esxi_device_id",
    "valueField":"vmw_esxi_vmfs_label",
    "aliasFieldName":"vmw_esxi_vmfs_name",
    "associatedFields":[
        "vmw_esxi_device_id"
    ]
  },{
    "name":"DatastoreFromScsiCorrelator",
    "filter":"scsiCorrelator storage Datastores naa*",
    "keyField":"vmw_esxi_device_id",
    "valueField":"vmw_esxi_datastore",
    "aliasFieldName":"vmw_esxi_datastore_name",
    "associatedFields":[
        "vmw_esxi_device_id"
    ]
  }],
    • example =
      event:
      alias:

IMPORTANT: You should NEVER manually edit a content pack.

This means that in version 4.0 of the vSphere content pack you get the following aliases:

  • Events that contain vmw_esxi_scsi_host_status_label (extracted field) get vmw_esxi_scsi_host_status (alias field)
  • Events that contain vmw_esxi_scsi_device_status_label (extracted field) get vmw_esxi_scsi_device_status (alias field)
  • Events that contain vmw_esxi_scsi_sense_status_label (extracted field) get vmw_esxi_scsi_sense_status (alias field)
  • Events that contain vmw_esxi_device_id (extracted field) get vmw_esxi_vmfs_name (alias field) and vw_esxi_datastore_name (alias field)

IMPORTANT: It is possible that the vmfs_name and datastore_name is the same, but this is not guaranteed (e.g. rename VM with storage VMotion). As such, both aliases are made available.

How it works

IMPORTANT: The requirements for the alias feature are:

  1. Log Insight 4.0 or newer
  2. VMware – vSphere content pack 4.0 or newer
  3. ESXi configured to log to LI
  4. A minimum of five minutes after the first event that contains both key and value it through the ingestion pipeline

Log Insight studies events stored in the repository and keeps track of any new or changed dynamic aliases. Every five minutes, any new or changed dynamic aliases are applied. All aliases appear as fields, which means the original message is never modified.

IMPORTANT: Unlike vROps inventory mapping, the latest learned alias is applied to all previous occurrences within the events. This means if the alias value changes over time, Log Insight only remembers / keeps track of the latest learned value and applies that to all events for a given query. This means aliases behave similar to extracted fields in that they are populated at query time. vROps inventory mapping are populated at ingest time so changes can be tracked over time.

It should be noted that alias fields are a new type of field. They are not 100% static nor 100% extracted. They are stored in a keyword index (like static fields), but are computed at query time (like extracted fields). As of Log Insight 4.0, aliases have a few limitations that should be noted:

  • Aliases can not be used with mathematical functions (e.g. avg, min, max)
  • Aliases can not be used with the “exists”/”does not exist” operators
  • Aliases are not forwarded as part of event forwarding
  • Up to 100,000 aliases can be learned per node then they are rotated out in a FIFO manner

Beyond Datastore IDs

I have already received some questions like does this aliasing support resolving datastore UUID to user-friendly names? The answer today is yes, however it requires two things:

  1. An event that comes the datastore UUID as well as the datastore name — turns out this already exists
  2. A definition added to the vSphere content pack — this is missing today, but stay tuned!

Summary

The Log Insight team takes customer experience seriously. The team is also very agile and works to get features out quickly so new feedback can be collected and features can be enhanced. What else would you like to see done with this aliasing feature? Be sure to comment here as well as on http://loginsight.vmware.com.

© 2017, Steve Flanders. All rights reserved.

Steve Flanders

One comment on “Log Insight 4.0: vSphere Datastore ID to Name Aliasing”

mryom0304 says:

So cool. Love the way it has been implemented!

Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

Back To Top