|
| 1 | +/*! |
| 2 | + * Copyright 2022 Google LLC |
| 3 | + * |
| 4 | + * Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | + * you may not use this file except in compliance with the License. |
| 6 | + * You may obtain a copy of the License at |
| 7 | + * |
| 8 | + * http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | + * |
| 10 | + * Unless required by applicable law or agreed to in writing, software |
| 11 | + * distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | + * See the License for the specific language governing permissions and |
| 14 | + * limitations under the License. |
| 15 | + */ |
| 16 | + |
| 17 | +import arrify = require('arrify'); |
| 18 | +import path = require('path'); |
| 19 | +import {google} from '../../protos/protos'; |
| 20 | +import {Entry} from '../entry'; |
| 21 | + |
| 22 | +// eslint-disable-next-line @typescript-eslint/no-explicit-any |
| 23 | +declare const global: {[index: string]: any}; |
| 24 | + |
| 25 | +// The global variable keeping track if instrumentation record was already written or not. |
| 26 | +// The instrumentation record should be generated only once per process and contain logging |
| 27 | +// libraries related info. |
| 28 | +global.instrumentationAdded = false; |
| 29 | + |
| 30 | +// The variable to hold cached library version |
| 31 | +let libraryVersion: string; |
| 32 | + |
| 33 | +// Max length for instrumentation library name and version values |
| 34 | +const maxDiagnosticValueLen = 14; |
| 35 | + |
| 36 | +export const DIAGNOSTIC_INFO_KEY = 'logging.googleapis.com/diagnostic'; |
| 37 | +export const INSTRUMENTATION_SOURCE_KEY = 'instrumentation_source'; |
| 38 | +export const NODEJS_LIBRARY_NAME_PREFIX = 'nodejs'; |
| 39 | +export type InstrumentationInfo = {name: string; version: string}; |
| 40 | + |
| 41 | +/** |
| 42 | + * This method returns the status if instrumentation info was already added or not. |
| 43 | + * @returns true if the log record with instrumentation info was already added, false otherwise. |
| 44 | + */ |
| 45 | +export function getInstrumentationInfoStatus() { |
| 46 | + return global.instrumentationAdded; |
| 47 | +} |
| 48 | + |
| 49 | +/** |
| 50 | + * This method helps to populate entries with instrumentation data |
| 51 | + * @param entry {Entry} The entry or array of entries to be populated with instrumentation info |
| 52 | + * @returns {Entry} Array of entries which contains an entry with current library instrumentation info |
| 53 | + */ |
| 54 | +export function populateInstrumentationInfo(entry: Entry | Entry[]): Entry[] { |
| 55 | + // Update the flag indicating that instrumentation entry was already added once, |
| 56 | + // so any subsequent calls to this method will not add a separate instrumentation log entry |
| 57 | + let isWritten = global.instrumentationAdded; |
| 58 | + global.instrumentationAdded = true; |
| 59 | + const entries: Entry[] = []; |
| 60 | + if (entry) { |
| 61 | + // eslint-disable-next-line @typescript-eslint/no-explicit-any |
| 62 | + for (const entryItem of arrify(entry) as any[]) { |
| 63 | + if (entryItem) { |
| 64 | + const info = |
| 65 | + entryItem.data?.[DIAGNOSTIC_INFO_KEY]?.[INSTRUMENTATION_SOURCE_KEY]; |
| 66 | + if (info) { |
| 67 | + // Validate and update the instrumentation info with current library info |
| 68 | + entryItem.data[DIAGNOSTIC_INFO_KEY][INSTRUMENTATION_SOURCE_KEY] = |
| 69 | + validateAndUpdateInstrumentation(info); |
| 70 | + // Indicate that instrumentation info log entry already exists |
| 71 | + // and that current library info was added to existing log entry |
| 72 | + isWritten = true; |
| 73 | + } |
| 74 | + entries.push(entryItem); |
| 75 | + } |
| 76 | + } |
| 77 | + } |
| 78 | + // If no instrumentation info was added before, append a separate log entry with |
| 79 | + // instrumentation data for this library |
| 80 | + if (!isWritten) { |
| 81 | + entries.push(createDiagnosticEntry(undefined, undefined)); |
| 82 | + } |
| 83 | + return entries; |
| 84 | +} |
| 85 | + |
| 86 | +/** |
| 87 | + * The helper method to generate a log entry with diagnostic instrumentation data. |
| 88 | + * @param libraryName {string} The name of the logging library to be reported. Should be prefixed with 'nodejs'. |
| 89 | + * Will be truncated if longer than 14 characters. |
| 90 | + * @param libraryVersion {string} The version of the logging library to be reported. Will be truncated if longer than 14 characters. |
| 91 | + * @returns {Entry} The entry with diagnostic instrumentation data. |
| 92 | + */ |
| 93 | +export function createDiagnosticEntry( |
| 94 | + libraryName: string | undefined, |
| 95 | + libraryVersion: string | undefined |
| 96 | +): Entry { |
| 97 | + // Validate the libraryName first and make sure it starts with 'nodejs' prefix. |
| 98 | + if (!libraryName || !libraryName.startsWith(NODEJS_LIBRARY_NAME_PREFIX)) { |
| 99 | + libraryName = NODEJS_LIBRARY_NAME_PREFIX; |
| 100 | + } |
| 101 | + const entry = new Entry( |
| 102 | + { |
| 103 | + severity: google.logging.type.LogSeverity.INFO, |
| 104 | + }, |
| 105 | + { |
| 106 | + [DIAGNOSTIC_INFO_KEY]: { |
| 107 | + [INSTRUMENTATION_SOURCE_KEY]: [ |
| 108 | + { |
| 109 | + // Truncate libraryName and libraryVersion if more than 14 characters length |
| 110 | + name: truncateValue(libraryName, maxDiagnosticValueLen), |
| 111 | + version: truncateValue( |
| 112 | + libraryVersion ?? getNodejsLibraryVersion(), |
| 113 | + maxDiagnosticValueLen |
| 114 | + ), |
| 115 | + }, |
| 116 | + ], |
| 117 | + }, |
| 118 | + } |
| 119 | + ); |
| 120 | + return entry; |
| 121 | +} |
| 122 | + |
| 123 | +/** |
| 124 | + * This method validates that provided instrumentation info list is valid and also adds current library info to a list. |
| 125 | + * @param infoList {InstrumentationInfo} The array of InstrumentationInfo to be validated and updated. |
| 126 | + * @returns {InstrumentationInfo} The updated list of InstrumentationInfo. |
| 127 | + */ |
| 128 | +function validateAndUpdateInstrumentation( |
| 129 | + infoList: InstrumentationInfo[] |
| 130 | +): InstrumentationInfo[] { |
| 131 | + const finalInfo: InstrumentationInfo[] = []; |
| 132 | + // First, add current library information |
| 133 | + finalInfo.push({ |
| 134 | + name: NODEJS_LIBRARY_NAME_PREFIX, |
| 135 | + version: getNodejsLibraryVersion(), |
| 136 | + }); |
| 137 | + // Iterate through given list of libraries and for each entry perform validations and transformations |
| 138 | + // Limit amount of entries to be up to 3 |
| 139 | + let count = 1; |
| 140 | + for (const info of infoList) { |
| 141 | + if (isValidInfo(info)) { |
| 142 | + finalInfo.push({ |
| 143 | + name: truncateValue(info.name, maxDiagnosticValueLen), |
| 144 | + version: truncateValue(info.version, maxDiagnosticValueLen), |
| 145 | + }); |
| 146 | + } |
| 147 | + if (++count === 3) break; |
| 148 | + } |
| 149 | + return finalInfo; |
| 150 | +} |
| 151 | + |
| 152 | +/** |
| 153 | + * A helper function to truncate a value (library name or version for example). The value is truncated |
| 154 | + * when it is longer than {maxLen} chars and '*' is added instead of truncated suffix. |
| 155 | + * @param value {string} The value to be truncated. |
| 156 | + * @param maxLen {number} The max length to be used for truncation. |
| 157 | + * @returns {string} The truncated value. |
| 158 | + */ |
| 159 | +function truncateValue(value: string, maxLen: number) { |
| 160 | + if (value && value.length > maxLen) { |
| 161 | + return value.substring(0, maxLen).concat('*'); |
| 162 | + } |
| 163 | + return value; |
| 164 | +} |
| 165 | + |
| 166 | +/** |
| 167 | + * The helper function to retrieve current library version from 'package.json' file. Note that |
| 168 | + * since we use {path.resolve}, the search for 'package.json' could be impacted by current working directory. |
| 169 | + * @returns {string} A current library version. |
| 170 | + */ |
| 171 | +export function getNodejsLibraryVersion() { |
| 172 | + if (libraryVersion) { |
| 173 | + return libraryVersion; |
| 174 | + } |
| 175 | + libraryVersion = require(path.resolve( |
| 176 | + __dirname, |
| 177 | + '../../../', |
| 178 | + 'package.json' |
| 179 | + )).version; |
| 180 | + return libraryVersion; |
| 181 | +} |
| 182 | + |
| 183 | +/** |
| 184 | + * The helper function which checks if given InstrumentationInfo is valid. |
| 185 | + * @param info {InstrumentationInfo} The info to be validated. |
| 186 | + * @returns true if given info is valid, false otherwise |
| 187 | + */ |
| 188 | +function isValidInfo(info: InstrumentationInfo) { |
| 189 | + if ( |
| 190 | + !info || |
| 191 | + !info.name || |
| 192 | + !info.version || |
| 193 | + !info.name.startsWith(NODEJS_LIBRARY_NAME_PREFIX) |
| 194 | + ) { |
| 195 | + return false; |
| 196 | + } |
| 197 | + return true; |
| 198 | +} |
| 199 | + |
| 200 | +/** |
| 201 | + * The helper method used to reset a status of a flag which indicates if instrumentation info already written or not. |
| 202 | + */ |
| 203 | +export function resetInstrumentationStatus() { |
| 204 | + global.instrumentationAdded = false; |
| 205 | +} |
![gcf-owl-bot[bot]](https://avatars.githubusercontent.com/in/99011?v=4&size=40){kind=avatar}
0 commit comments