Splunk® Style Guide

Splunk Style Guide

The guidelines in the Splunk Style Guide establish best practices for writing technical documentation. Search docs.splunk.com to find documentation related to Splunk products.

Formatting reference

Applying formatting to certain elements in text aids readers in their understanding of that text. Using consistent text formatting also helps readers scan text for the information they're looking for. Use these formatting conventions when you write Splunk documentation.

Documentation elements

Review the following table for formatting guidance on documentation elements:

Element How to format Examples Comments
Error messages Quotation marks for inline examples, monospaced font block for standalone examples
  • If you see an error message such as "Invalid input value", the add-on was unable to generate a certificate with the provided information.
  • When you view the logs in the <install_directory>/var/log/edge.log file on the host machine of the Edge Processor, the following error message appears:
"error":"HTTP 403 \"Forbidden\""
See Error and warning messages for more information.
Keyboard shortcuts No formatting Select Alt+N for Windows or *nix or Control+N for Mac. Don't include spaces in the shortcut. See Keyboard shortcuts for more information.
Manual names Italics, headline-style capitalization See Managing connections in the Splunk Data Stream Processor in the Connect to Data Sources and Destinations with DSP manual. See Manual names, topic titles, and section headings for more information.
Topic titles and section headings Sentence-style capitalization See Pass values to the class constructor in the Splunk Developer Portal. See Manual names, topic titles, and section headings for more information.
Words that are offset from the meaning of your sentence Quotation marks Search for "Query tables" on the Microsoft website.  

Computer elements

Review the following table for formatting guidance on computer elements:

Element How to format Examples Comments
Directories, folders, repositories No formatting
  • The $SPLUNK_HOME/bin/etc/apps folder
  • The \bin\etc\apps folder
  • The <your domain> folder
 Start partial directories with a forward slash ( / ) for *nix or a backslash ( \ ) for Windows. Enclose placeholder variables in angle brackets.
Expressions Inline monospaced font
  • Ensure delay > 10 evaluates to True.
  • The following regular expression defines valid identifiers for the scheme name: [0-9a-zA-Z][0-9a-zA-Z_-]*
  
File extensions No formatting
  • A text (.txt) file
  • A .tgz extension
  
File names No formatting Navigate to the fields.conf file.  
File paths No formatting
  • $SPLUNK_HOME/bin/splunkd
  • %SPLUNK_HOME%\bin\splunkd.exe
 List both the *nix and Windows file paths, in that order.
File types All capital letters
  • A TXT file
  • In JSON format
  • A PDF
  
Hosts and ports No formatting
  • http://localhost:8000
  • <deployment name>.splunkcloud.com
 Don't include formatting for the host or port. Enclose placeholder variables in angle brackets.
Placeholder variables Angle brackets
  • http://<hostname:port>
  • host=<your_hostname>
  
Tags (HTML, XML) Inline monospaced font
  • A <div> tag
  • The <dashboard> element
  
UI elements, including menu items, drop-down lists, buttons, text entry fields, panels, and dialog boxes Bold type
  • Select Settings, then Data inputs.
  • In the Set Source Type step of the Add Data guided setup, select Timestamp.
  • In the Name field, enter your name.
 Use the word "then" or equivalent text to separate the names of menus.
URIs, URLs See the Comments column
  • Open https://prod.spacebridge.spl.mobi/health_check in a web browser.
  • Open port 443 outbound to prod.spacebridge.spl.mobi to allow the WebSocket connection.
 Include http:// or https:// and www. Don't capitalize any letters in the link. Prevent fake links from rendering by using a <nowiki> tag or inline monospaced font.
User input in the UI Bold type
  • For the Destination field, enter ca_counties.
  • In the Title field, enter Top recipients by mailer.
  

Splunk-specific elements

Review the following table for formatting guidance on Splunk-specific elements:

Element How to format Examples Comments
Index names Bold type Save the file in the main index.  
Input names Bold type Select the myhost data input.  
Knowledge objects such as fields, event types, lookups, tags, aliases, and data models Inline monospaced font
  • The default field index identifies the index in which the event is located.
  • The IP address uses the mainoffice tag.
  
Searches Search bar or monospaced font block See the following topics for search examples: For guidance on line breaks in search tags, see Line breaks.
Search results Search table For a search result example, see untable in the Splunk Enterprise Search Reference manual.  
Source types Inline monospaced font This entry defines the access_combined source type.  
SPL and SPL2 clauses All capital letters
  • Use the WHERE clause to filter results.
  • The SPL2 from command has these clauses: FROM, JOIN, WHERE, GROUP BY, SELECT, ORDER BY, LIMIT, and OFFSET.
  
SPL and SPL2 commands, elements, functions, and macros Inline monospaced font
  • Enter | inputlookup ca_county_lookup to test your geospatial lookup.
  • Use the geom command to perform the lookup.
  • Use the apply function.
  • Include a custom metrics index in the itsi_im_metrics_indexes search macro.
  
Splexicon links Bold type Use geospatial lookups to return results that Splunk software can use to generate a choropleth map visualization. For guidance on Splexicon links, see Formatting links in Splunk documentation.
Tenant names Bold type
  • Use the system tenant.
  • Find the getstartedtutorial01 tenant.
  
Token names No formatting Update your access token.  
User roles and capabilities No formatting
  • You need the admin role to configure the settings.
  • If the user holds the admin_all_objects capability, they can make changes to any object on the instance.
  

Configuration files

Review the following table for formatting guidance on configuration files:

Element How to format Examples Comments
Attributes or settings Inline monospaced font
  • httpport
  • enableSplunkWebSSL
  
Configuration files in text Monospaced font block See the following topics for configuration file examples:  
Configuration file names No formatting Navigate to the fields.conf file.  
Configuration file parameters, arguments, and stanza names in a paragraph Inline monospaced font
  • Set the maxDist value to 60 in the fields.conf file.
  • Edit the [splunktcp] stanza.
 Enclose stanza names in square brackets.
Values Inline monospaced font
  • In the [settings] stanza, map httpport to 12800.
  • Set enableSplunkWebSSL=true.
  

Command-line interface (CLI) elements

Review the following table for formatting guidance on CLI elements:

Element How to format Examples Comments
A complete command Inline monospaced font See the following topics for command examples:  
Command line arguments in a numbered list or longer than 1 line Monospaced font block See the following topics for command line argument examples:  
Command line arguments in a paragraph Inline monospaced font You can also use the command line by entering ./splunk apply cluster-bundle in the CLI.  
Command names Inline monospaced font Run the btool command.  
Command options or parameters Inline monospaced font -u <username> Enclose placeholder variables in angle brackets.

REST API

Review the following table for formatting guidance on REST API elements:

Element How to format Examples Comments
API names No formatting
  • The collect2 API
  • You can securely store, update, retrieve, and delete secrets using the Splunk platform REST API.
  • Replace your token values, file path, and name of your app package in the Splunk AppInspect API.
  
Endpoints Bold type for endpoint name, monospaced font block for endpoint path Access the provisioner endpoint: 
/system/provisioner/v1beta1/tenants
Enter the endpoint name in bold. When referring to an endpoint path, use a monospaced font block.
HTTP or REST API methods All capital letters for method type, monospaced font block for usage Submit a GET request: 
GET /system/provisioner/v1beta1/tenants/
Enter the request name in all capital letters. When using a method and endpoint together, use a monospaced font block.
JSON bodies Monospaced font block See the following topics for JSON body examples:  
Object names Bold type the handle object  
REST API requests and responses Monospaced font block See the following topics for REST API examples:  
REST response body Monospaced font block See the following topics for REST response body examples:  
Request parameters Inline monospaced font "earliest_time": "-30m"  
Returned REST response value Inline monospaced font IACQlgX2dSVNz7HVDRA9StAm0j  

Code

Review the following table for formatting guidance on code:

Element How to format Examples Comments
Arguments Inline monospaced font Pass in arg1 as the argument for the param1 parameter and arg2 as the argument for the param2 parameter.  
Classes Inline monospaced font The MyClass class Capitalize class names with medial capitals.
Code elements and usage Inline monospaced font
  • Use operators such as +, !=, and AND.
  • Use keywords such as if, else, and return tags such as <div/>.
  
Code examples Monospaced font block See the following topics for code examples:  
Constants All capital letters DEBUG_STREAMEVENTS  
Function names in code Monospaced font block or inline monospaced font, depending on use Pass your arguments into the myFunction function. For example: myFunction(arg1, arg2) Most function names appear in code samples, where they are formatted as inline monospaced font in a sentence or within a code block as a standalone example.
Hexadecimal numbers All capital letters for alphabetical characters in the hexadecimal number
  • #FF0000
  • 0xFF0000
  • %FF0000
  • U+FF0000
  
HTTP status codes Inline monospaced font
  • 4xx
  • 503: Service too busy
 Use a lowercase "x" to represent a range.
Methods Inline monospaced font The myMethod method  
Parameters Inline monospaced font This function accepts 2 parameters, param1 and param2.  
Placeholder variables Angle brackets Open the /etc/apps/<your_app_name>/appserver/ folder.  
Properties Monospaced font block or inline monospaced font, depending on use Most properties appear in code samples, where they are formatted as a monospaced font block. Use inline monospaced font when referring to a property in a sentence.
Simple XML elements Inline monospaced font Find the <title>all</title> element.  
Simple XML source code for dashboards Monospaced font block For an example of Simple XML source code, see Simple XML Reference in the Splunk Enterprise Dashboards and Visualizations manual.  
User-created values Bold type The value of the myStr parameter is hello.  
Last modified on 14 February, 2024
Capitalization   Line breaks

This documentation applies to the following versions of Splunk® Style Guide: current

Acrobat logo Download manual
Acrobat logo Download this page

Was this topic useful?







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