Axibase Time Series Database Use Cases

Axibase Documentation Guide

The guide contains a compilation of grammar, punctuation, and Markdown formatting rules for software developers.

  • To comply with general Markdown syntax, use markdownlint.
  • To comply with all or subset of custom rules discussed in this guide, enable custom rules.

References:

Contents

Grammar

Abbreviations

  • Abbreviate if the acronym is known to the target audience.
  • Introduce new acronyms in parentheses and re-use thereafter.
    • ✅ Hadoop Distributed File System (HDFS) is a clustered system. HDFS is resilient.
  • Always abbreviate:
    • Known terms: SQL, API, REST, JVM, UTF, URL, URI.
      • ✅ SQL report
      • ⛔️ Structure Query Language (SQL) report
    • Data formats: CSV, JSON, XLS, XML, XLS, PDF.
    • Protocols: HTTP, HTTPS, SSL, JMX, TCP, UDP, SSH, DNS.
    • Standards and organizations: ISO, ASCII, ANSI, W3C.
    • Time zones: UTC, EST, GMT.
    • ATSD in Axibase documentation repositories.

Capitalization

  • Use title case in headers.

    • ✅ ## Import Data.
    • ⛔️ ## Import data.

  • Do not capitalize program/file/function names such as curl, atsd.log, even in headers.

    • ✅ ## Import Data with curl.
    • ⛔️ ## Import Data with Curl.

  • Do not capitalize the first word after the colon in a list.

    • ✅ Step 3: unzip files.

  • Do not capitalize file extensions.

    • ✅ .png, .xml, .jar.

  • Keep original product capitalization.

    • ✅ SQL Server Database, Hadoop, HBase.

  • In ambiguous cases, adhere to one option for consistency:

    • ✅ Unix, bash, IPv4, IPv6, URL.
    • ⛔️ UNIX, Bash, IP v4, IP v6, Url.

Contractions

  • Replace "i.e." or "e.g." with "for example".
    • ✅ Specify the recipient, for example `user@example.org`.
    • ⛔️ Specify the recipient, e.g. `user@example.org`.
  • "etc" is allowed.
  • Replace don't, can't, hasn't, isn't, didn't with do not, cannot, etc.
    • ✅ The parameter is not valid.
    • ⛔️ The parameter isn't valid.

Commas

  • Do not use a comma to separate clauses with multiple actors. Create separate sentences.
    • ✅ Submit the query. Review the results.
    • ⛔️ Submit the query, the result is displayed.

Colons

  • Begin lists with colons (:).
    • ✅ Execute the following commands to stop the database:
  • Separate list titles from their content with a colon.
    • ✅ Step 1: stop ATSD process.

Hyphens

  • Hyphenate compound adjectives.
    • ✅ Cancel a long-running query.
  • Do not hyphenate adverb adjectives that end with ly.
    • ✅ Review frequently used queries.
    • ⛔️ Load data from the publicly-accessible service.
  • Do not use a hyphen to separate title from meaning, use a colon.
    • ✅ Meta Query: retrieves metadata from the service.
    • ⛔️ Meta Query - retrieves metadata from the service.

Numbers

  • Write out numbers one through ten, unless they have units.
    • ✅ There are three ways to perform this calculation.
  • Write out ordinal numbers.
    • ✅ The first query causes the database to lock the table.
  • Add thousands separator except for milliseconds and machine output.
    • ✅ Stop the query if the row count exceeds 1,000.
  • Insert a space between a number and multiple-letter unit. Omit space for one-letter units.
    • ✅ 8 GB, 128 MB, 2 CPUs, 10%.

Parentheses

  • Do not use parentheses.
    • ✅ Execute `SELECT 1` query to test the connection.
    • ⛔️ Execute any query (such as `SELECT 1`) to test the connection.
  • Parentheses are allowed to spell out a number or character sequence.
    • ✅ The field supports wildcards (`*`).
    • ✅ Up to nine (`9`) fractions are printed.

Possessives

  • Do not use possessives.
    • ✅ Modify the file content or Modify the contents of the file.
    • ⛔️ Modify the file's content.

Quotation Marks

  • Do not use quotation marks.
  • To designate UI elements use bold text.
    • ✅ Click **View** to proceed.
    • ⛔️ Click on 'View' to proceed.
  • To designate single-line machine output use bold text or backticks.
    • ✅ Watch the log file for **Start completed** message.
    • ✅ Watch the log file for `Start completed` message.
    • ⛔️ Watch the log file for "Start completed" message.
  • To designate multiple-line machine output use code blocks with txt dialect.

Formatting

Backticks

Apply single backticks to the following:

  • File names: atsd.log.
  • Directory and file paths: /opt/atsd/atsd/conf/server.properties.
  • File extensions: .png, .xml.
  • Program names: curl, wget, cron.
  • Email addresses: user@example.org.
  • Host names and IP addresses: 127.0.0.1, 2001:db8::1.
  • HTTP methods: POST, GET.
  • HTTP status codes: 200 OK, 404.
  • HTTP status code ranges: 2xx, 3xx.
  • URI paths and query strings: /api/v1/{entity}/metrics.
  • Header names and values.
    • Set Content-Type header to application/json.
  • Function and procedure names.
  • Reserved SQL keywords and clauses.
    • Add condition to the HAVING clause.
  • Parameter, field, and variable names.
    • Reset `queue.policy` to `BLOCK` setting.
    • Locate the `github-notify` rule on the **Alerts** page.
  • Parameter, field, and variable values, including boolean values and numbers.
    • Set `limit` field to `16` batches.
  • Usernames.
    • Switch to `axibase` user.
  • Port numbers.
    • Make sure ATSD is listening on port `8443`.
  • Version numbers.
    • Python `3.5` is required for ATSD version `19420`.
  • Single-line machine output. Bold text is also allowed.
    • ✅ Watch the log file for `Start completed` message.
  • Shell commands: su, chown, sudo.

Exceptions:

  • Do not backtick an acronym, unless it represents a field or parameter value.
    • ✅ Select `GZIP` or `LZO` option in the **Codec** drop-down list.
    • ⛔️ The file is exported in `CSV` format.
  • Do not use backticks in headings.
    • ✅ ## Install Python 3.5 using curl.

Code Blocks

  • Fence code with triple backticks.
  • Fence multiple-line machine output with triple backticks.
  • Apply the correct dialect such as javascript or python.
    • Use txt for ASCII tables.
    • Use json for JSON documents, xml for XML files etc.
    • Use txt for machine output, unless the output is formatted, in which case use appropriate dialect.
    • Use ls for Charts configuration.
    • Use javascript for rule engine expressions.

Dates and Times

  • Spell out month if the format is ambiguous:
    • ✅ 01/Jun/2018.
    • ⛔️ 06/01/2018.
  • Do not use ordinal numbers in dates.
    • ✅ April 15.
    • ⛔️ April 15th.
  • Use commas with full dates.
    • ✅ The report was published on December 13, 2017.
  • Write time in 24-hour format.
    • ✅ April 15, 2018 at 20:30.
    • ⛔️ April 15, 2018 at 8:30 pm.

Headers

  • Use title case in headers.

    • ✅ ## Import Data from File.
    • ⛔️ ## Import data from file.

  • Do not use backticks in headers.

    • ✅ ## Configure cron.
    • ⛔️ ## Configure `cron` schedule.

  • Do not terminate sentences in headers with dot.

    • ⛔️ ## Import data from file.

  • Avoid punctuation symbols in headers except colon (:).

    • ⛔️ ## Import Data from File (Directory).
  • Use relative paths when linking markdown files in the same repository:
    • ✅ Initiate a [restart](../../administration/restarting.md).
    • ⛔️ Initiate a [restart](/administration/restarting.md).
  • When linking to documents in the same repository, link to markdown files, and not to https://axibase.com/ URLs:
    • ✅ Initiate a [restart](../../administration/restarting.md).
    • ⛔️ Initiate a [restart](https://axibase.com/docs/atsd/administration/restarting.html).
  • Describe the linked document in the link title:
    • ✅ Review [installation notes](install.md).
    • ⛔️ Click [here](install.md) to view installation notes.

Style

Active Voice

  • Maintain active voice for technical documentation.
    • ✅ The database filters metrics based on user settings.
    • ⛔️ Metrics are filtered based on user settings
  • Describe both the actor and the action, or use the imperative to instruct a user.
    • ✅ Log in to ATSD web interface to import the CSV file on the CSV Parsers page. Configure upload settings to filter unneeded metrics.
    • ⛔️ When the CSV file is imported, unneeded metrics are filtered.

Blacklisted Words

word alternatives
should use must or remove
could -
would -
may can
will use present tense
was use present tense
were use present tense
had use present tense
abort stop, cancel
kill stop, cancel
terminate stop, cancel
admin administrator
so, a lot use formal style
deselect clear
uncheck clear
flag option, setting
ingest load, import
lets -
please -
regex regular expression
Epoch time Unix time
datacenter data center
and/or clarify the meaning
in order to to
make sure ensure
end-point endpoint
click on click
robust avoid trite words

Example Names

  • IPv4 address: 192.0.2.1, 198.51.100.1, 203.0.113.0 per RFC 5737.
  • IPv4 address range: 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24.
  • IPv6 address: 2001:db8::1 per RFC 3849.
  • IPv6 address range: 2001:db8::/32.
  • Phone number: (800) 555-0100.
  • Host name: atsd_hostname, atsd_ip_address.
  • DNS name: example.org per RFC 2606, localized domains.
  • Subdomain: test.example.org, atsd.example.org.
  • Organization: Example Foundation, Example Corporation. Avoid Contoso.
  • Email: user@example.org, test@example.org, john.doe@example.org.
  • First name: John, Jack, Jane, Mary.
  • Last name: Doe, Smith, Jones.
  • Credentials: username and password, username:password, and john.doe:secret in examples.
  • SSN: 000-00-0000.
  • File path: /path/to/new-dir, /path/to/new-file. Replace new-dir and new-file to indicate the purpose, for example, /path/to/backup-dir.

Interface Elements

  • Interface elements must be bold, exactly as they appear in the UI.
  • Add > to describe navigation sequences.
    • ✅ Open the **Alerts > Rules** page.
  • Do not include types for named elements: button, split-button, checkbox, drop-down list, field, link, switch.
    • ✅ Click **Next**.
    • ✅ Select `CSV` from **File Format**.
    • ✅ Open the **Rules** page.
    • ⛔️ Click **Next** button.
    • ⛔️ Select `CSV` from the **File Format** drop-down list .
  • Use consistent UI element types:
    • button
    • split-button (not multi-action button, drop-down button, combo-button)
    • checkbox (not checkbox)
    • drop-down list (not drop-down menu)
    • tab
    • link
    • page
    • button
    • switch (not selector)
    • window
    • dialog window (not popup window)
    • left menu (also main menu)
    • top menu
  • Use "the" article when referring to the element by type.
    • ✅ Click the **Web Notifications** tab
    • ⛔️ Click **Web Notifications** tab
  • Use log in as verb and login as noun.
    • ✅ Log in to ATSD.

Issue Subjects

  • Add prefix (topic) to subject. The topic can repeat the category or clarify it if necessary.
    • ✅ UI: SQL Query Statistics page error.
  • Use regular case (not title case) in the subject.
  • Use the imperative for features.
    • ✅ Storage: Add table details to data consistency page.
  • Use descriptive sentences for bugs.
    • ✅ NMON Parser: property record is not updated.

Functions

  • Use present tense for function descriptions. Omit the noun.
    • ✅ Returns a collection of alert history records.
    • ✅ Returns the natural logarithm of x.
    • ⛔️ This function returns a collection of alert history records.
    • ⛔️ Return a collection of alert history records.

Phrasing

  • Remove verbiage, such as execute these steps, follow the prompts, perform these tasks, by executing the following command.
    • ✅ Create a Slack [workspace](https://slack.com/create).
    • ⛔️ Go to https://slack.com/create and follow the prompts to create a new workspace.
    • ✅ Remove the ephemeral `/hbase` directory from Zookeeper cache.
    • ⛔️ Execute the command to remove the ephemeral `/hbase` directory from Zookeeper cache.
    • ✅ Add nmon to crontab to collect the data constantly.
    • ⛔️ Setup crontab with the following commands so that nmon will collect the data constantly.
  • Describe what the command does.
    • ✅ Launch the `inotify` script to watch for file changes.
    • ⛔️ Run the script with the following command:
  • Favor example over sample.
    • ✅ Example configuration:
    • ⛔️ Sample configuration:

Present Tense

  • Do not use will, was, were, had. Write in the present tense.
    • ✅ Collector starts the job immediately.
    • ⛔️ Collector will start the job immediately.

Product Names

  • Use original product names unless you introduce an abbreviation.
  • Articles can be omitted from product names in most cases.
    • ✅ Axibase Time Series Database
    • ⛔️ The Axibase Time Series Database

Variables

  • Use curly brackets ({}) to designate a variable in URI path or query string:
    • ✅ /api/{entity}/metrics
    • ✅ /api/metrics?id={metricId}
  • Use camelCase in compound variable names in REST API:
    • ✅ entityGroup
    • ⛔️ entity-group
  • Add "the" article before the variables with types.
    • ✅ Open the `atsd.log` file.
    • ⛔️ Open the file `atsd.log`.

Configuration

Automated Checks

Configure Travis CI to check custom rules as part of the pull request workflow.

Travis

Custom Rules

The repository contains custom rules for identifying inconsistencies and style violations.

Rule Scope

To enable or disable rules within a given Markdown file, wrap the text with non-printable HTML comments.

  • Disable all rules: <!-- markdownlint-disable -->
  • Enable all rules: <!-- markdownlint-enable -->
  • Disable specific rules: <!-- markdownlint-disable MD001 MD002 -->
  • Enable specific rules: <!-- markdownlint-enable MD001 MD002 -->

For example:

<!-- markdownlint-disable MD037 -->
deliberate space * in * emphasis
<!-- markdownlint-enable MD037 -->

To disable the rule for the entire *.md file, add the markdownlint-disable marker before the first header.

A markdownlint-enable marker is not necessary in this case.

Feedback? Comments?