Splunk® Enterprise

Search Reference

Download manual as PDF

Download topic as PDF

metadata

Description

The metadata command returns a list of source, sourcetypes, or hosts from a specified index or distributed search peer. The metadata command returns information accumulated over time. You can view a snapshot of an index over a specific timeframe, such as the last 7 days, by using the time range picker.

See Usage.

Syntax

| metadata type=<metadata-type> [<index-specifier>]... [splunk_server=<wc-string>] [splunk_server_group=<wc-string>]...

Required arguments

type
Syntax: type= hosts | sources | sourcetypes
Description: The type of metadata to return. This must be one of the three literal strings: hosts, sources, or sourcetypes.

Optional arguments

index-specifier
Syntax: index=<index_name>
Description: Specifies the index from which to return results. You can specify more than one index. Wildcard characters (*) can be used. To match non-internal indexes, use index=*. To match internal indexes, use index=_*.
Example: | metadata type=hosts index=cs* index=na* index=ap* index=eu*
Default: The default index, which is usually the main index.
splunk_server
Syntax: splunk_server=<wc-string>
Description: Specifies the distributed search peer from which to return results. If you are using Splunk Cloud, omit this parameter. If you are using Splunk Enterprise, you can specify only one splunk_server argument. However, you can use a wildcard when you specify the server name to indicate multiple servers. For example, you can specify splunk_server=peer01 or splunk_server=peer*. Use local to refer to the search head.
Default: All configured search peers return information
splunk_server_group
Syntax: splunk_server_group=<wc-string>...
Description: Limits the results to one or more server groups. If you are using Splunk Cloud, omit this parameter. You can specify a wildcard character in the string to indicate multiple server groups.

Usage

The metadata command is a generating command and should be the first command in the search. Generating commands use a leading pipe character.

The command shows the first, last, and most recent events that were seen for each value of the specified metadata type. For example, if you search for:

| metadata type=hosts

Your results should look something like this:

This image shows a table of metadata information by host. The fields are host, type, firstTime, lastTime, recentTime, and totalCount.

  • The firstTime field is the timestamp for the first time that the indexer saw an event from this host.
  • The lastTime field is the timestamp for the last time that the indexer saw an event from this host.
  • The recentTime field is the indextime for the most recent time that the index saw an event from this host. In other words, this is the time of the last update.
  • The totalcount field is the total number of events seen from this host.
  • The type field is the specified type of metadata to display. Because this search specifies type=hosts, there is also a host column.

In most cases, when the data is streaming live, the lastTime and recentTime field values are equal. If the data is historical, however, the values might be different.

In small testing environments, the data is complete. However, in environments with large numbers of values for each category, the data might not be complete. This is intentional and allows the metadata command to operate within reasonable time and memory usage.

Time ranges

If you specify a time range other than All Time for your search, the search results might not be precise. The metadata is stored as aggregate numbers for each bucket on the index. A bucket is either included or not included based on the time range you specify.

For example, you run the following search specifying a time range of Last 7 days. The time range corresponds to January 1st to January 7th.

| metadata type=sourcetypes index=ap

There is a bucket on the index that contains events from both December 31st and January 1st. The metadata from that bucket is included in the information returned from search.

Maximum results

By default, a maximum of 10,000 results are returned. This maximum is controlled by the maxresultrows setting in the [metadata] stanza In the limits.conf file.

Examples

1. Search multiple indexes

Return the metadata for indexes that represent different regions.

| metadata type=hosts index=cs* index=na* index=ap* index=eu*

2. Search for sourcetypes

Return the values of sourcetypes for events in the _internal index.

| metadata type=sourcetypes index=_internal

This returns the following report.

This image shows a table of information for the _internal index by sourcetype.

3. Format the results from the metadata command

You can also use the fieldformat command to format the results of the firstTime, lastTime, and recentTime columns to be more readable.

| metadata type=sourcetypes index=_internal | rename totalCount as Count firstTime as "First Event" lastTime as "Last Event" recentTime as "Last Update" | fieldformat Count=tostring(Count, "commas") | fieldformat "First Event"=strftime('First Event', "%c") | fieldformat "Last Event"=strftime('Last Event', "%c") | fieldformat "Last Update"=strftime('Last Update', "%c")

Click on the Count field label to sort the results and show the highest count first. Now, the results are more readable:

This image shows how the results of renaming the fields returned by the metadata command.

4. Return values of "sourcetype" for events in a specific index on a specific server

Return values of "sourcetype" for events in the "_audit" index on server foo.

| metadata type=sourcetypes index=_audit splunk_server=foo

See also

dbinspect
tstats

Answers

Have questions? Visit Splunk Answers and see what questions and answers the Splunk community has using the metadata command.

PREVIOUS
map
  NEXT
metasearch

This documentation applies to the following versions of Splunk® Enterprise: 6.3.0, 6.3.1, 6.3.2, 6.3.3, 6.3.4, 6.3.5, 6.3.6, 6.3.7, 6.3.8, 6.3.9, 6.3.10, 6.3.11, 6.3.12, 6.4.0, 6.4.1, 6.4.2, 6.4.3, 6.4.4, 6.4.5, 6.4.6, 6.4.7, 6.4.8, 6.4.9, 6.5.0, 6.5.1, 6.5.1612 (Splunk Cloud only), 6.5.2, 6.5.3, 6.5.4, 6.5.5, 6.5.6, 6.5.7, 6.6.0, 6.6.1, 6.6.2, 6.6.3, 6.6.4, 6.6.5, 7.0.0, 7.0.1


Comments

Woodcock - The “get_metadata" is the capability that controls this. The “user” role has this capability by default.

Lstewart splunk, Splunker
October 2, 2017

After some admin changes to roles, we lost the ability to run the metadata command: This user has insufficient permissions to get metadata. You have insufficient permissions to get metadata. What capability controls this and might that be worth documenting here?

Woodcock
September 19, 2017

Woodcock
The metadata command is not based on the tstats command. If it is helpful for you to think of the firstTime field as max(_time) that is great but it would be misleading to state that the metadata command is essentially a macro around tstats.

Lstewart splunk, Splunker
September 12, 2017

It helps to know this (I think it should be on this page somewhere besides the comment section):

The metadata command is essentially a macro around tstats. For the clueful, I will translate:
The "firstTime" field is "min(_time)".
The "lastTime" field is "max(_time)".
The "recentTime" field is "max(_indextime)".

I commented about this here:
https://answers.splunk.com/answers/567047/metadata-showing-wrong-last-indexed-time.html?childToView=567064#answer-567064

Woodcock
August 31, 2017

Woodcock
Confirmed with the Search Language team and added the tstats command to the See Also section.

Lstewart splunk, Splunker
April 25, 2017

The "See Also" section should include tstats, too.

Woodcock
April 19, 2017

Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters