Naming Conventions

Audience

This document is primarily intended for (internal) team members of the Splunk Service team at Illinois. We make this page broadly available, however, because we often need to reference this material for other audiences:

• Our customers who serve in the role as data managers — i.e., Splunk users who are also (typically) systems or app administrators
• Software Developers who need to produce and send log data
• Support staff from Splunk, Inc.

Indexes

Indexes are “collections” of logs organized (out of necessity) 1) by access permissions (which often equates to unit/group affiliation) and 2) by retention period (how long logs are retained). In addition, as deemed necessary or desirable, some very large log sources may best be separated out in order to optimize search performance. (Very large indexes with a very diverse set of keywords across the sources can lead to poor search performance.) Collecting logs in to indexes oriented around “constructs” (implying similar sorts of keywords or fields) can, most importantly, help keep indexes optimized for search; it also provides an organizing principle for a very large, multi-tenant environment; and it can provide another (easy) way to include/exclude indexes from searches (e.g., index=servers-*).

We have developed “collection” name standards (see table further below) around which we will work with you to name / organize your indexes. Our intent is for these standards to help us keep indexes in our shared environment organized and performant.

To demonstrate, below is a sample (make-believe) scenario for index creation for a unit that evolves over time. We encourage you to think ahead for your unit as much as possible. 

Phase 1 (Throw server logs in one place. It’s ok for all persons in unit with access to Splunk to have the same access and for data to expire after 30 days.)

• servers_mycollege – Default, 30 day retention (all logs on all servers going to a ‘servers’ index).

Phase 2 (Someone decides these groups need differentiated access: linux, windows, web / Marketing & Communications, devops teams)

• servers-windows_mycollege – 30 day retention
• servers-linux_mycollege – 30 day retention
• web_mycollege – 30 day retention. IIS and apache logs go here for web/devops/marcomm teams. OS-level logs still go to ‘server’ indexes.
• apps-acme3_mycollege – 30 day retention. OS logs still go to ‘server’ indexes, but logs directly related to “ACME3”, perhaps including some IIS access logs, now go to this index for DevOps team.

Phase 3 (Person responsible for quarterly/annual reporting needs runs in to issue with 30-day retention and lack of relationship of data from logs to structured data from EDW.)

• summary_mycollege – 2 year retention. Scheduled searches are constructed to summarize key metrics from windows access logs, web logs, app logs.
• lookups_mycollege – 7 day retention. Data is pulled in from EDW through these ‘lookup indexes’ to produce lookup files (Splunk-internal .csv tables) to add meaningful context (e.g., better labels) to reports/dashboards.

Phase 4 (Someone decides to store metrics for machine learning and other uses in metrics indexes)

• servers-metrics_mycollege – 30 day retention
• apps-acme3-metrics_mycollege – 1 year retention

When naming an index, it can help to ask…

• Does an index based on the collection name standards already exist that fits the collection of logs under consideration? (Can help promote consistent application of convention.)
• If so, should this collection of logs go there? (Are differentiated access and retention required? Re access differentiation, promote a collaborative, “open but monitored” approach.) If not, should it be named similarly?

Naming convention:

{collection}[-{sub-collection}][-devtest][-metrics][_{scope}][_{group/unit}][-{subgroup}]

Examples:

general_business

A “general” index for the College of Business

network_urbana_techsvc

An index of network-related logs with a scope of the Urbana campus network for Technology Services

datacenters-aws_techsvc

An index of log sources related to AWS technologies for Technology Services

datacenters-short_engineering

An index of log sources related to data center technologies with a “short” retention period for the College of Engineering

servers-linux_ncsa

An index of log sources from linux servers at NCSA

servers-windows_las

An index of log sources from Windows servers at the College of LAS

servers-windows-devtest_las

An index of log sources from test Windows servers at the College of LAS

security-ossec_splunk_techsvc

An index of the alerts generated by the OSSEC agents installed on the Splunk servers managed by the Technology Services Splunk Team

endpoints_urbana_techsvc

An index of log sources from endpoints on the Urbana campus for Technology Services

apps-mydot_engineering

An index of log sources from the MyDot application framework from the College of Engineering.

apps-blackboard-academicrecord_techsvc

An index of log sources from the blackboard application that contains academic records (reflecting need for longer retention period) for Technology Services.

Guidelines:

• Use lower-case
• Use hyphens and underscores as prescribed. (No spaces.) Note that hyphens should be used to separate within a logical construct and underscores used to separate the logical constructs.
• If/when a group needs/desires separate indexes, use the collection name standards (below) as a guide.
• Use {scope} to represent a concept beyond / other than “unit/group”, such as geographic location (e.g., “urbana”).
• For {unit/group} we recommend using the unit/group’s standardized short-name, such as the prefix used for AD naming convention or domain name, etc.
• If a separate index is needed because of specific retention needs, use a sub-collection descriptor that reflects the rationale for the differentiated retention (e.g., “-studentdata”) rather than a specific value (e.g., “-90d”). In this way, retention periods can be changed for the purpose reflected in the construct (i.e., in the case of this example, the construct of “student data”) without changing the index name (and all of its references).
• Regarding “devtest”, “test”, and “dev”. If “test” or “dev” refers to the source (e.g., test servers, or dev servers), then add “devtest” as a sub-collection. If “test” or “dev” refer to the purpose of the index (e.g., you are exploring a new or different way to ingest data from a source) and if a designation is required to avoid confusion between the test/dev index and an index in production, append “_temp” or “_devtest as appropriate to the index name.

Collection name standard (as needed/desired)	Sub-collection (as needed/desired)	Description / Explanation
general		Recommended for indexes that contain general (any) logs for the specified group.
network	network-firewall, network-wireless, network-vpn, network-dns, network-dhcp, etc.	As needed, intended for all network devices / technologies such as switches, routers, firewalls, etc.
datacenters	datacenters-vmware, datacenters-aws, etc.	As needed, intended for logs from on-premises (physical or virtual) or cloud-based “datacenter” technologies such as power management, storage management, virtual machine management, monitoring and alerting, integration or automation solutions, AWS, Azure, cloud broker, etc.
servers	servers-linux, servers-win, etc.	As needed, intended for logs for servers.
endpoints	endpoints-mac, endpoints-win, endpoints-mobile, endpoints-printers, etc.	As needed, intended for logs of endpoints and endpoint-associated solutions such as endpoint-management solutions (e.g., sccm), mobile-device-management solutions (e.g., airwatch), etc.
apps	apps-box, apps-compass, etc.	As needed, specific applications / application frameworks, web-based or otherwise.
db	db-mssql, db-mysql, db-rds, etc.	As needed, intended for logs for Oracle, MS SQL, postgres, mysql, etc.
web	web-iis, web-apache, etc.	As needed, intended for logs for IIS, apache, etc.
iam	iam-siteminder_aits, iam-shibboleth_techsvc	As needed, intended for logs for authentication and authorization – AD, ldap, shibboleth, siteminder, etc.
security	security-duo	As needed, intended for logs for security-centric solutions such as SIEM (Security Information and Event Management) solutions, bro, honey pots, etc.
facilities	facilities-powermonitor_fs	As needed, intended for logs for “smart” facilities: power monitors, doors, lights, card swipes, presence sensors, etc.

Sourcetypes

A Splunk sourcetype is a description of a log file (or data stream) format or pattern. For example, the pre-trained “syslog” sourcetype tells Splunk to watch for a pattern of text with timestamp at or near the beginning of a line, to separate events when it sees a line-break, and to look for possible key/value pairs paired with an equals sign (=) and surrounded by whitespace, etc.; the “CSV” sourcetype tells Splunk the file is going to have a header row of field names, and then additional rows of double-quote-surrounded field values separated by commas; “_json” sourcetype tells Splunk to look for nested structures like [ { element/fieldname:”value”, } ], etc. A sourcetype and its many parameters help Splunk know what an event looks like, how to tell one event from another, where to find and interpret the timestamp, and even how to extract key fields — all in order to make your data more useful, more searchable. As you can see, a sourcetype is not a “store”, but a “definition” or “map” with many configurable options. An index can have as many sources (log files, data streams) as appropriate (bound by permissions and retention configuration), and a source may have one or more sourcetypes (i.e., different patterns). I.e., the relationship between indexes and data sources is one-to-many and the relationship between data sources (and indexes) to sourcetypes is many-to-many.

For data from very established technologies, one should always look to see if a pre-existing sourcetype (or sourcetypes) exists for the data source either from Splunk or the vendor of the technology. In many cases, it may be advisable to use a pre-trained sourcetype (such as those described above)  — as they are occasionally improved by Splunk (and/or vendor) over time. Consequently, one may see improvements in ingestion quality (and CIM-alignment).

However…  It is the sourcetype definition in Splunk that one will most often want to use for custom configurations of one’s data. For example, if you need to create a field extraction, a field alias, or a field calculcation (for example, that combines field value a with field value b), you will (most likely) want to tie this to the sourcetype.  There are three paths one can take for customizations of pre-trained (or 3rd-party) sourcetypes: A) Use pre-trained sourcetype but make customizations specific to an “app” context, B) Use pre-trained sourcetype but make customizations and apply them to entire ‘Illinois’ Splunk environment (requires admin action), C) Clone the sourcetype, effectively ‘branching’ the sourcetype for your own purposes (can be limited to app context or made global).  When cloning, it is recommended to retain the original (pre-trained) sourcetype name and add a suffix to represent the custom application. (See convention below.)

When the data being ingested does not conform to a pre-trained sourcetype from Splunk (or provided by a 3rd party app), one needs to create a new sourcetype altogether. Please follow the naming convention below.

ASIDE: As part of helping you make the most of your data, one can “normalize” fields from your data using the Common Information Model (CIM) as a foundation (and/or, where appropriate, extending CIM with new data models and normalized fields). Normalizing your fields can help you with correlational analysis, but also provides you with a path a) to accelerated data models and pivot tables, and b) to leverage other solutions (e.g., Splunk or 3rd-party “apps”) available from Splunk or technology vendors that require CIM compliance. Aligning your data  to the CIM is something that can be achieved manually or through a vendor’s “Technical Add-on”. Typically CIM-alignment is achieved through sourcetype-specific configurations.

For altogether new sourcetypes (or even to inform modifications to cloned sourcetypes), please review Splunk’s proposed naming convention for sourcetypes.

NOTE: Splunk has changed its sourcetype naming convention over time. The old style uses underscore separators (e.g., access_combined) while the new style uses colon separators (e.g., ibm:ldap:audit). The recent style also provides (new) guidance in terms of hierarchical structure (left-to-right).

Convention:

Old style… (deprecated, but still useful when cloning old-style sourcetypes)

{old_style_pre-trained_sourcetype}[_{modifier(s)}][_{version}]

New style… (Reference Splunk’s proposed naming convention for sourcetypes.)

[{vendor|institution}][:product][:technology][:format]

Examples:

illinois:rokwire:app:json

A sourcetype for product “rokwire” (developed at Illinois) of app data in JSON format.

ibm:idsi:authc:syslog

A sourcetype for product “IDSI” (Directory Services) from IBM of authentication data in ‘syslog’ format.

access_combined_ncsa-extended

A sourcetype derived from the apache standard “access_combined” format, created to accommodate the ‘NCSA-Extended/Combined’ variation.

csv_etext

A sourcetype derived from the standard, pre-trained ‘csv’ sourcetype with minor modifications for the etext app log format.

_json_blackboard

A sourcetype derived from the standard, pre-trained ‘_json’ sourcetype with minor modifications for the blackboard log format.

cpanel

A specific app’s general log sourcetype.

cpanel:error

A sourcetype for a specific app’s error logs. Needed only if the error log file format is not the exact same as the format of the file used for the ‘cpanel’ sourcetype.

cpanel:php-fm:error

A sourcetype for a specific error log for a specific sub-function of an application. Necessary only if the format of the source log file is not exactly the same as the cpanel_error sourcetype.

ossec:alerts

The sourcetype for the OSSEC alerts.log file found locally on the servers where OSSEC is installed for file integrity monitoring and intrusion detection.

bb:authentication

A custom sourcetype for a specific app’s authentication logs. Needed only if the error log file format does not already exactly match another pre-existing log format such as the generic blackboard log type.

WinEventLog:Security

This example is included to demonstrate how common log files often lead to industry standard sourcetype names even though they may not be listed by Splunk as a pre-trained sourcetype. This example does conform to the conceptual framework of our local convention, but varies in its use of camel-case and a colon for a separator.

Guidelines / Explanations:

• Use lower-case.
• Default to colon (:) as separator, use hyphen when necessary as a “lesser” separator.
• RE “Primary Entity Defining the Log Format”: Sometimes it’s an open log file format (e.g., apache log standard used by many web servers), sometimes it’s an app (e.g., mysqld), sometimes it’s a vendor standard (cisco_syslog, or WinEventLog). Use the entity that best represents whatever is driving the format of the data source. Try to use the generic name of the entity, rather than a localized or custom name for the sourcetype (for example, “confluence” instead of “wiki”, or “blackboard” instead of “compass”). This maximizes the re-usability of the sourcetype should we have a need to ingest the exact same format and content structure in another context.

Splunk Roles

Splunk uses roles for access management – and all roles are created within the context of a search head. In a large, multi-tier, multi-tenant environment such as ours, we create fidelity by breaking roles down in to three areas: Capabilities (what kinds of actions one can take on a search head), Indexes (what indexes one can access from the search head), Apps (access to an app and the objects associated with it).

Convention(s):

Search Head Capability Roles: (Few and static)

    cpb{-role}[_{searchhead-name}][_{unit/group}]

Index Roles: (Typically only one per index. By default, replicated on all search heads for consistent access.)

    idx_{index-name}

    sf_{index-name}[{_filter-desc}]

App Roles: (One or more of each per app context)

    app_{app-folder-name*}[-read|-write][_{unit/group}]

Examples:

cpb-user_splunk-on-ramp

Role for basic user capabilities on the search head, “splunk-on-ramp”.

idx_compass_techsvc

Role for access to the index, “compass” owned by “techsvc”.

cpb-analyst_illinois

Role for Analyst (akin to Splunk’s “Power User”) capabilities on the “illinois” search head.

idx_apps-wiki_techsvc_excl-courses

Role for a user with a filter (to restrict access by omitting logs related course wiki spaces) on the “apps-wiki_techsvc” index.

cpb-analyst-privileged_illinois-es

Role for Analyst on search head “illinois-es”. (This privileged role requires a demonstration of requisite skills.)

app_ritp-read

Role for read access to the app set up for use by the Research IT Portal (ritp).

app_ritp-write

Role for write access to the app set up for use by the Research IT Portal (ritp).

 

Guidelines / Explanations:

• Use lower-case
• Use hyphens and underscores as prescribed. (No spaces.) Note that hyphens should be used to separate within a logical construct and underscores used to separate the logical constructs.
• RE {role}: Predefined roles are “user”, “analyst”, “datamanager”. Custom roles are acceptable.
• RE app-folder-name: 1) Omit the “organization” and “site” prefix (which are part of the folder name convention). For example, “illinois-urbana-apps-blackboard_techsvc” should be “apps-blackboard_techsvc”.
• RE {role-qualifier}: Only include role qualifier if role is “filtered” (role includes explicit search and/or data restrictions) or “privileged” (permissions granted are based on skill / training of members).  NOTE – Users should not have more than 1 filter role applied due to ‘srchFiltr’ inheritance issues. This limitation (as of the writing of these guidelines) may lead us to recommend a custom account for use cases requiring filters.
• RE {index} v {search head}: Roles can be multi-faceted. Because of the complexity of our environment, we recommend a) one role per index (as you might expect) and b) one role per search head.
• RE {unit/group}: Only append _{unit/group} if it adds meaningfully to what unit/group is (or should be) identified in the index name or search head name. I.e., include it if unit/group isn’t in the index or search head name or if the role is for a unit/group different from the unit/group of the index or search head.

Directory Service Groups

We use an integration of AuthMan (Grouper) and Microsoft Active Directory (AD) groups for managing membership in Splunk roles. There should be one Authman (and one corresponding AD) group for each role in our Splunk environment. The below is less “guidance” and more “description” of how these entities are created based on automation. Preferrably, AuthMan groups are created by script; but if created manually, should follow the convention below. 

Convention:

Type	Folders (Grouper “stems”)	Groups (Grouper)		Roles (Splunk)
team	urb:app:splunk:service:adhoc:<unit[:subunit]:team|tech>	<team|tech>_<profile_role> Essential: <team|tech>_data-managers <team|tech>_analysts Common: <team|tech>_users Less common: <team|tech>_developers <team|tech>_external_analysts <team|tech>_upstream_analysts <team|tech>_external_users <team|tech>_upstream_users <team|tech>_viewers
cpb	urb:app:splunk:service:policy:cpb	<cpb_role>_<search_head> Core: data-manager_illinois analyst_illinois power-analyst_illinois user_illinois Other (for example) add-data_gui_illinois app-dev_illinois dispatch_to_rest		cpb_<cpb_role>_<search_head> Core: cpb_data-manager_illinois cpb_analyst_illinois cpb_power-analyst_illinois cpb_user_illinois Other (for example) cpb_add-data_gui_illinois cpb_app-dev_illinois cpb_dispatch_to_rest
idx	urb:app:splunk:service:policy:idx	(1:1 to Splunk Role) <index_name> Example: network-firewall_techsvc		idx_<index_name> Example: idx_network-firewall_techsvc
sf	urb:app:splunk:service:policy:idx	sf_		sf_
app (profile)	urb:app:splunk:service:policy:app	<team|tech>_<profile_role> (1:1 to Splunk Role) Essential: <team/tech>_analyst Common: <team/tech>_user Rare: <team_tech>_viewer Other (for example): <team_tech>_pii-privileged		app_<team|tech>_<profile_role> Essential: app_<team/tech>_analyst Common: app_<team/tech>_user Rare: app_<team_tech>_viewer Other (for example): app_<team_tech>_pii-privileged

 

AuthMan Group (the originating group)

app:splunk:cpb|idx|app:{splunkrole-without-prefix}

   where “{splunkrole-without-prefix}” is a variable representing the Splunk role established within Splunk (see Role naming convention above), but without its app|cpb|idx prefix.

AD Group (For use by Shibboleth)

app-splunk-cpb|idx|app-{splunkrole-without-prefix}

URN (Used for mapping SAML attribute from Shibboleth to Splunk Role)

urn:mace:uiuc.edu:urbana:authman:app-splunk-app|cpb|idx-{splunkrole-without-prefix}

Example

AuthMan Group

urb:app:splunk:cpb:analyst_illinois

   a group for persons granted “Analyst” role within the “illinois” search head.

AD Group

urb-app-splunk-cpb-analyst_illinois

URN

urn:mace:uiuc.edu:urbana:authman:urb-app-splunk-cpb-analyst_illinois

Guidelines:

• Use lower case only
• It is assumed {splunkrole} conforms to the role naming convention which specifies unit/group and either index or search head.

IMPORTANT: If creating manually, enter originating requester or group admin responsible for that group in the Notes field. (Future state desired: Originator / Owner is made owner of AuthMan Group.)

Dashboards, Panels, Reports, Alerts, Searches

Dashboards, Dashboard Panels, Searches, Reports, and Alerts lend themselves to descriptive names that may be presented to the end user. Our recommendation reflects both this usage and the way Splunk Web’s user interface supports more descriptive names.

Note that many Knowledge Objects (KOs) can’t be renamed once created. Most KOs can be “cloned”, but the clone will be a new object.  (Reference: https://docs.splunk.com/Splexicon:Knowledgeobject )

Convention:

{Brief but meaningful summary description}[ {Time-range-representation}][ {Version}][ {Date}][{Unit/Group}]

Examples:

Windows Console Logons -1d

A report of windows console logons from the past day.

Windows Console Logons -1d v3.6

The same report that reflects a version number.

Network Switch Errors -5m TechSvc

A report to reveal network switch errors in the last five minutes.
“TechSvc” is added here – but is usually not required because the app it exists in provides that kind of context. But some reports – if they’re stored in a “cross-campus” app (like Search & Reporting app), it may help to identify ownership/scope.

Guidelines:

• Use natural capitalization and spacing for readability. For searches, reports, and alerts, imagine the title as a header for the knowledge object.
• Use hyphens and underscores. Avoid spaces and other characters that are not URL-friendly. (This not only helps with shorter, more meaningful URLs within the product, it also helps reduce complexity of Search Head usage analytics.) Note that hyphens should be used to separate within a logical construct and underscores used to separate the logical constructs.
• Brief but meaningful description: Describe in the most succinct and natural way what this knowledge object is/does. See examples.
• Time interval (optional): If appropriate to assume the specified time interval is “prior to now”, use single interval (e.g., “30d”). If beginning and end times of range need to be specified, use a hyphen between the two. (e.g., 120d-90d).
• Version (optional): We recommend a typical representation with a lower-case “v”. E.g., “_v3.6_”
• Date (optional): We recommend YYYYMMDD format. E.g., “_20180506_”. Adding a date can help us identify objects that may have become obsolete over time.
• Unit/Group (optional): It is important that all knowledge objects that will be visible across different apps (or within a single app used by multiple groups) be associated with a unit/group for purposes of tracking down a responsible party – e.g., for troubleshooting or clean-up efforts.

Lookups, Field Extractions, Fields, Aliases, Tags, Event Types, Workflow Actions, Views, Times

Compared to names for Dashboards, Reports, Alerts, Searches, names for these objects tend to be more “internal”, less “end-user” oriented. Consequently, the Splunk Web interface for entering names for these objects is different and our recommendations for naming reflect these differences. While Splunk Web may allow you to enter spaces in the name, it will transform the spaces (in different ways depending on the context – sometimes dropping the space, sometimes replacing it) and not retain a pretty (“label”) version of the name. Capitalization is usually but not always retained.

Default recommendation is keep it simple: Use lower-case with underscore separator.

Note that many Knowledge Objects can’t be renamed once created. Most Knowledge Objects can be “cloned”, but the clone will be a new object.  (Reference: https://docs.splunk.com/Splexicon:Knowledgeobject )

Convention:

{short_name}

Examples:

country_name.csv  (lookup file)   country_name  (lookup definition)

country_name_collection (kv store)  country_name (lookup definition)

index_detail_deployment

capacity_planning   (view)

uid_user   (field)

Guidelines:

• Soft, default recommendation / guideline: Use lower-case and underscore. That said, hyphens and capitalization are often supported and, depending on the context, may be appropriate.
• If representing pre-existing names within a new name, for example, a field name within a field extraction, consider using a normalized field name from CIM. But if no corresponding normalized field from CIM and you want to make it clear how the extraction relates to fields used in the event data, it is fine to match the field name as presented in the event data. For example, if a field “course_composite” is not getting extracted and you want to extract it and name it, “course_composite” is fine, “course_composite” is fine, “courseComposite” is fine.
  Avoid special characters in field names, especially spaces, quotes, brackets, pipes, etc.
• Version (optional): If you find a situation where you need to manage ‘versions’, we recommend a typical representation with a lower-case “v”. E.g., “_v3.6_”. This is often most useful for saving older versions that you may need to revert to. For example, active object name “country_name”, with previous version “country_name_v3.6”
• Unit/Group: Not needed if you will be limiting visibility of the Knowledge Object within your own custom group/unit/team app. May be helpful/useful if/when the object is saved as “global” or “All apps”.

Lookup Files, KV Store Lookups, and Lookup Definitions

Lookup files are CSV-formatted tables (dataframes) of text.  Always name a lookup file with .csv suffix.

KV Store Lookups are internal MongoDB collections – provided as a solution for larger volume lookups, or lookups that need much faster performance.

A lookup definition gives you a way to create an “abstraction” so a lookup that starts out as a .csv could eventually become a _collection, and the end user need not know it.  A definition will reference the source lookup (either a csv or a kv store).

Examples:

sccm-device-inventory.csv  (file)  sccm-device-inventory  (definition)

sccm-device-inventory_collection  (kv store)  sccm-device_inventory (definition)

wireless-ap-locations_v3.6_20180506_techsvc.csv

Guidelines:

and include a date and revision attribute in order to facilitate the identification and removal of stale content. As with other no-space naming conventions, use hyphens for word separator within construct, and underscore to separate between constructs.

Custom Apps

In Splunk, an “App” is a very broad term, encompassing a wide variety of types of “bundles” of configurations / objects. Suffice it to say that a “bundle” of Splunk “stuff” together is an “App”.

An app has two names: “Folder Name” (field “title” inside Splunk, born out of unix directory name) and “Name” – which we will refer to below as “Display Name” (field “label” inside app.conf file in Splunk).

Two Conventions: “Local” v “Splunk Cloud / Splunkbase”

Splunk’s guidance on naming conventions for custom apps — especially apps destined for Splunkbase and/or Splunk Cloud — has evolved over time. We need to conform to their guidance for Splunk Cloud apps because apps that get installed in Splunk Cloud are actually installed in a private space in Splunkbase. But those limits need not apply to our locally constructed “configuration bundle” apps (such as those created on Deployment Server) that we send to Universal Forwarders. Consequently, we have two conventions for two “categories” of Splunk “apps”:

Apps destined for Splunk Cloud / Splunkbase

Here is guidance from Splunk’s “app.conf” document regarding Folder Names for apps destined for Splunkbase and/or Splunk Cloud:

id = <appid>
* id should be omitted for internal-use-only apps which are not intended to be
  uploaded to Splunkbase
* id is required for all new apps uploaded to Splunkbase. Future versions of
  Splunk Enterprise will use appid to correlate locally-installed apps and the
  same app on Splunkbase (e.g. to notify users about app updates)
* id must be the same as the folder name in which your app lives in
  $SPLUNK_HOME/etc/apps
* id must adhere to cross-platform folder-name restrictions:
  * must contain only letters, numbers, "." (dot), and "_" (underscore) characters
  * must not end with a dot character
  * must not be any of the following names: CON, PRN, AUX, NUL,
      COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9,
      LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9

Conventions:

Display Names:

{Brief but meaningful summary description} [Team ][ - {Scope}][ - {Unit/Group}]

Folder Names:

{organization}_{site}[_{scope}]_{short-name}[_{unit/group}]_APP|TA|DA|SA|CONF

Examples:

Display Name: Research IT Portal Team – TechSvc

Folder Name: uofi_urb_datamgr_APP

A custom app created for the Research IT Portal team (at Tech Services) to develop reports, dashboards, etc.

Display Name: Splunk Data Manager – Illinois

Folder Name: uofi_urb_datamgr_APP

A custom app intended for use by all Splunk @ Illinois customers who have role of Data Manager.

More foldername examples:

uofi_urb_datamgr_APP

The Data Manager app (bundle) including dashboards, reports, and canned inactivated alerts

uofi_spr_lrng_succ_APP

An analytics app (bundle) for a University of Illinois at Springfield Campus Learning Success initiative

uofi_urb_splunkmgmt_deplclient_CONF

The deployment server app for the Urbana Campus

uofi_urb_splunkmgmt_aws_outputs_CONF

Routing for outputs to the Urbana managed AWS forwarding tier

Guidelines / Clarifications:

• Keep foldernames as short as possible and still meaningful. Long foldernames can lead to issues (e.g., exit_code=255 errors) on search head. (App foldernames are the only meaningful factor over which we have control to mitigate that error/bug.)
• Splunk recommends underscore instead of hyphen to minimize potential OS-specific, file-system-related incompatibilities. TODO UNHANDLED WIKITAG: <ac_emoticon ac_name=”question”></ac_emoticon> ENDWIKITAG  Also reference the “Portable Filename” standard (from IEEE Std 1003.1-2017).
• Organization: uofi
• Site: urb, chi, spr
• Scope (optional):  “all” means all with a * for all things that connect to the deployment server, rarely used. “splunkmgmt” for administrative apps.
• For technology-specific “barebones” apps that are *not* 3rd party apps, use {Technology Name} – {Unit/Group} for label (Display Name). I.e., use suffix to make it easily distinguishable from a 3rd-party app named by the 3rd party.
• Use “Team” for custom apps intended for Splunk customer teams as opposed to apps oriented around a specific technology. I.e., use word “Team” to make “Team” apps easily distinguishable from Technology-specific apps. (Don’t include ‘team’ string in foldername to minimize length.)
• Unit/Group in Folder Names (optional): To keep foldername short, use only when meaningful – when contention with other units/groups can be anticipated.
• Unit/Group in Display Names (optional, encouraged): Add when meaningful. It will be helpful, for example, when multiple groups need a similarly named app – for example, several units might want “Web Analytics”. If LAS and Engineering both want such an app, it will be critical to add suffix for Unit/Group.
• APP|TA|DA|SA|CONF – APP should be used for apps which deliver reports, dashboards, alerts, etc. TA (Technology Add-on) for data collection without visualizations or other search-time KOs. DA (Domain Add-ons) and SA (Security Add-ons) are for Splunk Enterprise Security Apps and will rarely be used. CONF is used when customizing the app for management reasons and not search-time analysis of data.
  • You should consider breaking apart your app into an App and TA when working in a distributed environment where collection and searching will be distributed.
  • For example, an app that does custom linebreaking on an Illinois Wiki log should be created as uofi_urb_ts_wiki_TA and pushed to the Illinois Wiki application server’s universal forwarder and/or the Indexing Tier for parsing. A separate bundle that contains Illinois Wiki dashboards and reports would be named uofi_urb_ts_wiki_APP.
• Precedence: Due to ‘precedence’ rules in Splunk, it may be important to understand how Splunk determines what configurations (and apps) take precedence over another. Sorting is based on UTF-8 ASCII character set. Note the relative location of cross-platform-safe characters ‘.’ (dot), ‘-‘ (hyphen), and ‘_’ (underscore).
  

  Character	Character Name	UTF-8 (hex.)	Unicode code point
  !	EXCLAMATION MARK	21	U+0021
  “	QUOTATION MARK	22	U+0022
  #	NUMBER SIGN	23	U+0023
  $	DOLLAR SIGN	24	U+0024
  %	PERCENT SIGN	25	U+0025
  &	AMPERSAND	26	U+0026
  ‘	APOSTROPHE	27	U+0027
  (	LEFT PARENTHESIS	28	U+0028
  )	RIGHT PARENTHESIS	29	U+0029
  *	ASTERISK	2a	U+002A
  +	PLUS SIGN	2b	U+002B
  ,	COMMA	2c	U+002C
  –	HYPHEN-MINUS	2d	U+002D
  .	FULL STOP	2e	U+002E
  /	SOLIDUS	2f	U+002F
  0	DIGIT ZERO	30	U+0030
  1	DIGIT ONE	31	U+0031
  2	DIGIT TWO	32	U+0032
  3	DIGIT THREE	33	U+0033
  4	DIGIT FOUR	34	U+0034
  5	DIGIT FIVE	35	U+0035
  6	DIGIT SIX	36	U+0036
  7	DIGIT SEVEN	37	U+0037
  8	DIGIT EIGHT	38	U+0038
  9	DIGIT NINE	39	U+0039
  :	COLON	3a	U+003A
  ;	SEMICOLON	3b	U+003B
  <	LESS-THAN SIGN	3c	U+003C
  =	EQUALS SIGN	3d	U+003D
  >	GREATER-THAN SIGN	3e	U+003E
  ?	QUESTION MARK	3f	U+003F
  @	COMMERCIAL AT	40	U+0040
  A	LATIN CAPITAL LETTER A	41	U+0041
  B	LATIN CAPITAL LETTER B	42	U+0042
  C	LATIN CAPITAL LETTER C	43	U+0043
  D	LATIN CAPITAL LETTER D	44	U+0044
  E	LATIN CAPITAL LETTER E	45	U+0045
  F	LATIN CAPITAL LETTER F	46	U+0046
  G	LATIN CAPITAL LETTER G	47	U+0047
  H	LATIN CAPITAL LETTER H	48	U+0048
  I	LATIN CAPITAL LETTER I	49	U+0049
  J	LATIN CAPITAL LETTER J	4a	U+004A
  K	LATIN CAPITAL LETTER K	4b	U+004B
  L	LATIN CAPITAL LETTER L	4c	U+004C
  M	LATIN CAPITAL LETTER M	4d	U+004D
  N	LATIN CAPITAL LETTER N	4e	U+004E
  O	LATIN CAPITAL LETTER O	4f	U+004F
  P	LATIN CAPITAL LETTER P	50	U+0050
  Q	LATIN CAPITAL LETTER Q	51	U+0051
  R	LATIN CAPITAL LETTER R	52	U+0052
  S	LATIN CAPITAL LETTER S	53	U+0053
  T	LATIN CAPITAL LETTER T	54	U+0054
  U	LATIN CAPITAL LETTER U	55	U+0055
  V	LATIN CAPITAL LETTER V	56	U+0056
  W	LATIN CAPITAL LETTER W	57	U+0057
  X	LATIN CAPITAL LETTER X	58	U+0058
  Y	LATIN CAPITAL LETTER Y	59	U+0059
  Z	LATIN CAPITAL LETTER Z	5a	U+005A
  [	LEFT SQUARE BRACKET	5b	U+005B
  	REVERSE SOLIDUS	5c	U+005C
  ]	RIGHT SQUARE BRACKET	5d	U+005D
  ^	CIRCUMFLEX ACCENT	5e	U+005E
  _	LOW LINE	5f	U+005F
  `	GRAVE ACCENT	60	U+0060
  a	LATIN SMALL LETTER A	61	U+0061
  b	LATIN SMALL LETTER B	62	U+0062
  c	LATIN SMALL LETTER C	63	U+0063
  d	LATIN SMALL LETTER D	64	U+0064
  e	LATIN SMALL LETTER E	65	U+0065
  f	LATIN SMALL LETTER F	66	U+0066
  g	LATIN SMALL LETTER G	67	U+0067
  h	LATIN SMALL LETTER H	68	U+0068
  i	LATIN SMALL LETTER I	69	U+0069
  j	LATIN SMALL LETTER J	6a	U+006A
  k	LATIN SMALL LETTER K	6b	U+006B
  l	LATIN SMALL LETTER L	6c	U+006C
  m	LATIN SMALL LETTER M	6d	U+006D
  n	LATIN SMALL LETTER N	6e	U+006E
  o	LATIN SMALL LETTER O	6f	U+006F
  p	LATIN SMALL LETTER P	70	U+0070
  q	LATIN SMALL LETTER Q	71	U+0071
  r	LATIN SMALL LETTER R	72	U+0072
  s	LATIN SMALL LETTER S	73	U+0073
  t	LATIN SMALL LETTER T	74	U+0074
  u	LATIN SMALL LETTER U	75	U+0075
  v	LATIN SMALL LETTER V	76	U+0076
  w	LATIN SMALL LETTER W	77	U+0077
  x	LATIN SMALL LETTER X	78	U+0078
  y	LATIN SMALL LETTER Y	79	U+0079
  z	LATIN SMALL LETTER Z	7a	U+007A
  {	LEFT CURLY BRACKET	7b	U+007B
  |	VERTICAL LINE	7c	U+007C
  }	RIGHT CURLY BRACKET	7d	U+007D
  ~	TILDE	7e	U+007E