Recommendations for Record and Field Names

Common Standards for Long Names

The short names used for both records and fields are still used as the key, in addition, the short name is the only identifier stored internally in databases and display documents. This means we can change the long names without fear of breaking existing packaging. However, the short name is still important. Even though this document does not provide a standard for short names, you should use your best efforts to provide meaningful short names.

The common standards for long record and field names are as follows:

  • Do not use spaces anywhere.
  • Do not use any characters outside the range a-z, A-Z, 0-9. That is, do not use underscores, percent signs, dashes, dots etc
  • Industry standard and generally accepted acronyms should be used to keep record names as short as possible. E.g., TcpIp, Arp, Icmp, Db
  • All acronyms are to be capitalized (e.g. CPU becomes Cpu, NT becomes Nt, TCP/IP becomes TcpIp). At times this may look a bit silly but when applied to all acronyms and all records the look is quite appealing and, of course, standard.
  • Do not abbreviate words. For example, use NtNetworkInterface rather than NtNetInt.

Long Record Names

Do not use plural names. For example, use NskUser rather than NskUsers.


Each long record name should use the following format:

<platform>[<category>]<entity-name>…[D|R]

Where:




<platform> is one of:

Nsk – HPE NonStop NSK

UNIX – UNIX and Linux

Nt – Windows NT, 2000 and XP

Win9x – Windows 9x

Win – Windows 9x, NT, 2000 and XP and later

Mp – records provided on more than one platform

PROGNOSIS – internal records


<category> is optional but should be used to group related entities together.

Examples that use a category:

NskMeasureDevice
NskMeasureDiscOpen
NskMeasureDiskFile

Examples without a category

NskJob
NskFileDetail
NskFileException


<entity> is the specific entity for which the record provides information. Entity names may be followed by entity-name-specific qualifications.


For example: 

NtSubnetTrafficProtocolPort


Windows Only

[D|R]Optionally, and only when needed to differentiate records with the same name, a Database or Registry flag can be appended to the name. Use with care! This is very confusing to the user.

For example:

OracleLibraryCacheR
OracleLibraryCacheD
OracleBufferCacheR
OracleBufferCacheD

Long Field Names

Field names should follow similar naming standards to records, in that the category should precede the entity name or type to ensure that when they are viewed in alphabetical order like fields are together.

It is very difficult to have completely consistent field names and have the names easily guessed. This standard is a compromise between consistency and ease of use.

For HPE NonStop Records: We must be cognisant of the HPE NonStop platform’s long history with Prognosis. Many fields are well known and recognized by our field sales staff and customers. In many cases, it will be necessary to deviate from the standard to remain visually “backwards compatible”. This is acceptable as long as long field names are consistent across all HPE NonStop records. For example, the standard would normally call for the field name ProcessId, however, on HPE NonStop we may choose to continue to use Pid as the field name.

For NT Performance Monitor Records: Where possible you should try to use the record and field names as displayed in Microsoft Performance Monitor for records provided from the Performance Registry, however, still apply the standards detailed in Common Standards for Long Names. This way customers will be able to transfer any prior knowledge of those counters into their experience with Prognosis.

  1. Generally speaking, names that refer to actual entities should prefix field names. E.g., ProcessParentId, FileFlag.
  2. Use plural unless otherwise specified below. E.g., ReturnedBytes, SentBytes. For interval counts, do not use “NumberOf” or “TotalNumber”, instead use plural; it is always assumed that a field’s value represents a count for the interval. For example, use Jobs for the number of jobs executing in a CPU or Users for the number of users logged on or ActiveStreams for the number of active media streams in the interval.
  3. However, if a field is an ever-increasing total then drop the plural and add the suffix “Total”. E.g., CallTotal, ByteTotal, ErrorTotal.
  4. If a field is a rate add the suffix “PerSecond”. E.g., InterruptsPerSecond
  5. If a field is a state add the suffix “State”. E.g., DeviceState
  6. Pay careful attention to the key field(s). If it identifies the record, which in most cases it will, use the convention <record-name>Name, <record>Number or <record>Id. E.g., DeviceName, NodeNumber, ConferenceBridgeName, UserId. For NT Performance Registry records avoid using InstanceName as it adds no value. Use the correct suffix for the platform. For example, the suffix Id may be appropriate for a user on UNIX (UserId) but would be inappropriate for NT where UserName is typically used. Use Id when
    the field is alphanumeric or contains special characters E.g., a HPE NonStop user id.
  7. Note that point 3.6 does not apply to data fields, only identifying fields. For example, the NskNetBatch record has two key fields JobName, JobNumber along with SchedularProcessName. The key fields that have generic names (Number, Name) need to have the record name prefix. However, data fields like Class and State that are not key fields do not need to have “Job” prepended because the entire record represents a single instance of the job! You only need to add the entity name in front of the key fields.
  8. Elapsed time fields should have the suffix “Duration”. E.g., EventDuration, OutageDuration.
  9. If an ID field exists elsewhere containing the name entity type, use the same naming conventions. E.g., the NskCpu record has CpuNumber as the ID field. The Jobs record has a field describing the cpu of the ancestor process. In this case, the field name would be AncenstorCpuNumber rather than AncestorCpu.
  10. Fields indicating a size should include the units the size is measured in. E.g. FileSizeKB, ReadMBAverage.
  11. Note that acronyms, where the case is important, should use the correct case, such as MB for megabytes (as Mb is megabits). This does not apply to acronyms such as TCP and IP which should follow our own capitalization standard.

Some other conventions

  1. Use of StartTime and EndTime (even though in theory start/stop and begin/end go together).
  2. Feel free to interchange <entity><description> and <description><entity> to get more favourable groupings within the record. eg. either of FailedRequests or RequestsFailed may be acceptable depending on the other fields in the record. Try to be consistent for this field across records on the same platform though.
  3. No need to use Average unless there is a need to differentiate between this and other fields in the record (it is the default) eg. ResponseTime is ok but if you have a ResponseTimeMaximum you may choose to call ResponseTime ResponseTimeAverage
  4. On NSK, always use DeviceType and DeviceSubtype (meaning the device type and subtype numbers) even where the record is about a "device" for consistency across records. Ditto for FileCode.
  5. On NSK for disk/file space fields, use Allocated meaning space taken on disk and Used for the subset of allocated space that actually has data in it.
  6. On NSK use CpuNumberPrimary and CpuNumberBackup, and ProcessIdPrimary and ProcessIdBackup to group primary and backup PIDs/CPUs.
  7. For fields whose only reason for existence is as a breakdown of another field, prefix the breakdown field with the name of the other field (ie. treat it as a type qualifier like Maximum). eg. BusyPercentX25 and BusyPercentSystem in NskCpu record. This gets them grouped nicely with the "master" field. Note: Reads/Writes are not treated this way.

In general, the field name should follow the pattern:

<Entity>[<Description>][<Units>][<Type>]

Examples:

FileSizeKB
FileSizeKBMaximum
ReadMBAverage
FileSpaceMBGrowth

Some acceptable abbreviations:

  • Tle -  Time List Element (scope NSK records)
  • Atm - Automated Teller Machine (scope Base24 records)
  • Pos - Point Of Sale (scope Base24 records)
  • Url - Uniform Resource Location
  • Eof - End of File (scope NSK file records)
  • Dcom - Disk Compression Utility (scope NSK)
  • Tcp - Terminal Control Process (scope Pathway records)
  • TermPool - TERMPOOL setting in Pathway TCP (scope Pathway TCP record)
  • Pathmon - Pathway Monitor Process (scope NSK)
  • Linkmon - Pathway Link Monitor Process (scope NSK)
  • Tmf - Transaction Monitoring Facility (scope NSK)

Some acceptable types:

  • Peak, Used in place of Maximum for the highest value of rate field over a number of intervals. e.g. TransactionsPerSecondPeak
  • UserId, Meaning numeric user id (scope - NSK)
  • Flag, Yes/No, Y/N, or ON/OFF fields (scope - all platforms).
  • Configured, To mean a "maximum" configured in the system for something eg. ProcessControlBlocksConfigured
  • Last, To identify the most recent occurrence of something. e.g. LastTransactionResponseTime
  • Previous, Used as a suffix to denote that this is a historic figure representing the value of this field before it last changed
  • PriorToPrevious, Used as a suffix to denote this is the value of this field in the interval prior to the previous one.
  • Sum, Total of all things in this interval eg. CallDurationSum for the sum of all call durations for this interval. Total (as defined in the standard) would imply an incrementing total.
  • Interval, To describe a (typically configured) constant interval of time (duration wouldn't be appropriate). eg. MonitoringInterval
  • Change, For the difference in the field since last interval (non space related so Growth wouldn't be appropriate). eg. ResponseTimeChangePercent
  • Delay, Alternative to Duration for configured time to delay before doing something
  • CpuSeconds, For CPU time (where the use of Time would be inconsistent and the use of Duration would be misleading).

Field Types and Recommended Suffixes

Type of Field

Suffix

Special Notes

Examples

Count for interval

[None; this is the default field type assumption]

Plural

Retries, Interrupts, Users, RetriesLayer3

Rate per second

PerSecond

Plural

InterruptsPerSecond, FaultsPerSecond

Ever increasing total

Total

Singular

CallTotal, ErrorTotal

Maximum

Maximum

Singular

MemoryMBMaximum

Minimum

Minimum

Singular

MemoryMBMinimum,

LinkControlBlockFreeMinimum, CallDurationMinimum

State

State

Singular

DeviceState

Timestamp

Time

Singular

EventTime, StartTime, StopTime

Duration or elapsed time

Duration

Singular

EventDuration

Identifying fields

Name | Number

| Id

Singular

AncestorName, AncestorSystemName, UserNumber, UserId

Response Time

ResponseTime

Singular

ResponseTime, ActionResponseTime

Percentage

Percent

Singular

CpuBusyPercent, TransactionBusyPercent, MemoryQueuePercent, HourDownPercent, DownPercent (for the refresh down percent)

OSI Model Layers

Layer<n>


BytesLayer4, PacketsLayer2PerSecond

Range

[use words to describe the range]


MessagesLessThan4KPerSecond

Enums

Type

Singular

DeviceType, NodeType

Ratio

Ratio

Singular

InputByteRatio

Threshold

Threshold

Singular

FullActionThreshold, ResponseTimeThreshold

Size / Space

Size<increment>

Singular

FileSpaceMN

Growth

Growth

Singular

FileSpaceMBGrowth

Queue length

QueueLength

Singular

CpuQueueLength, ReceiveQueueLength

Space

<unit size>

Singular

SpaceFreeMB, SpaceAvailableMB, FileSizeKB

Provide feedback on this article