Имея более 200 плагинов, Telegraf имеет широкий спектр методов очистки, записи и запроса данных в InfluxDB и обратно. Однако иногда пользователям необходимо выполнить сбор данных за пределами возможностей Telegraf. Возможно, им нужно собирать пользовательские данные и отслеживать производительность приложений. Возможно, они хотят воспользоваться внешними инструментами и библиотеками для создания красивых веб-визуализаций для своих пользователей. В этих случаях имеет смысл воспользоваться преимуществами клиентских библиотек InfluxDB. Сегодня мы сосредоточимся на том, как использовать новейшую клиентскую библиотеку JavaScript InfluxDB с InfluxDB 2.0.
Важное примечание: InfluxDB v1.8 включает в себя как движок Flux для запросов, так и API записи HTTP InfluxDB v2. Это означает, что если вы не совсем готовы использовать InfluxDB v2 сегодня и планируете использовать новые клиентские библиотеки, вы можете это сделать! Эти параметры совместимости для чтения и записи позволяют вам защитить свой код в будущем!
Требования к учебнику и настройка
Это руководство было выполнено в системе MacOS с Node, установленным через Homebrew, в соответствии с документацией Node.js.
#update brew before installing
brew update
brew install node
#check to make sure you have successfully installed Node and NPM
node -v
npm -v
Самый простой способ начать работу с JavaScript-клиентом InfluxDB v2 — клонировать каталог примеров в репозиторий influxdb-client-js.
После того, как вы успешно клонировали каталог, перейдите к нему и запустите:
npm install
Укажите параметры авторизации в index.html
и env.js
. Вам нужно будет указать организацию, сегмент и токен. Теперь мы готовы начать использовать клиент в браузере:
npm run browser
Npm должен открыть http://localhost:3001/examples/index.html, где вам будет предложено написать точку данных в протоколе строки и запросить ее через пользовательский интерфейс. Вы также сможете зарегистрировать пользователя и выполнить проверку работоспособности API.
Параметры авторизации
ИнфлюксДБ v2
Чтобы использовать клиент, вам необходимо собрать следующие параметры:
- Имя или идентификатор сегмента: следуйте этой документации, чтобы создать сегмент. Чтобы просмотреть свои корзины, используйте пользовательский интерфейс или выполните
influx -t <your-token> -o <your-org> bucket find
- Токен: следуйте этой документации, чтобы создать токен. Чтобы просмотреть свои токены, либо используйте пользовательский интерфейс, либо выполните
influx auth find
- Организация: чтобы просмотреть свои организации, используйте пользовательский интерфейс или выполните
influx org find
InfluxDB v1.8 и выше
Если вы планируете использовать эту новую клиентскую библиотеку с InfluxDB 1.8 или более поздней версии, вот несколько важных советов по сбору необходимых параметров авторизации:
- Имя корзины. В InfluxDB v1.x нет концепции корзины. Однако ведро — это просто комбинация имени базы данных и ее политики хранения. Таким образом, вы можете указать это, указав имя базы данных InfluxDB 1.x и политику хранения, разделенные косой чертой (/). Если вы не укажете политику хранения, будет использоваться политика хранения по умолчанию.
Например: имя сегмента telegraf/1week
позволяет вам записать базу данных InfluxDB 1.x с именем «telegraf» с политикой хранения с именем «1week». Точно так же telegraf
/ или telegraf
позволяют вам писать в базу данных InfluxDB 1.x с именем «telegraf» и политикой хранения по умолчанию (обычно autogen
).
- Токен. В InfluxDB v2 токены API используются для доступа к платформе и всем ее возможностям. InfluxDB v1.x использует комбинацию имени пользователя и пароля при доступе к HTTP API. Укажите свое имя пользователя и пароль InfluxDB 1.x, разделенные двоеточием (:), чтобы обозначить токен. Например:
username:password
- Org: параметр org игнорируется в режиме совместимости с InfluxDB v1.x и может быть оставлен пустым.
Запись в InfluxDB v2 с помощью клиентской библиотеки JavaScript
Точка, которую вы пишете в демонстрационном примере, жестко закодирована и включает измерение, ключ тега и значение тега. Код генерирует следующий протокол строки temperature,example=index.html value=28.7
со следующей функцией:
function writeExample(value) { const writeApi = influxDB.getWriteApi(org, bucket) // setup default tags for all writes through this API writeApi.useDefaultTags({location: 'browser'})
log('\n*** WRITE ***') const point1 = new Point('temperature') .tag('example', 'index.html') .floatField('value', value) writeApi.writePoint(point1) log(` ${point1}`) // flush pending writes and close writeApi writeApi .close() .then(() => { log('WRITE FINISHED') }) .catch(e => { log('WRITE FAILED', e) }) }
Вы предоставляете свою организацию и корзину методу getWriteApi, который создает WriteApi. Этот метод также позволяет включать параметр точности для поддержки несколько меток времени с точностью, значение по умолчанию равно ns.
Существует несколько методов форматирования данных для записи линейного протокола в InfluxDB.
- Метод useDefaultTags указывает API использовать теги по умолчанию, определенные пользователем при записи точек.
- Метод writeRecord принимает одну строку протокола.
- Метод writeRecords принимает массив строк строкового протокола.
Существует два метода записи данных линейного протокола в InfluxDB.
- writePoint поддерживает одну запись.
- writePoints поддерживает несколько записей.
Запрос InfluxDB v2 с помощью клиентской библиотеки JavaScript
ИнфлюксДБ v2
Теперь, когда мы записали случайные данные о температуре в наш экземпляр InfluxDB, мы готовы запросить их.
function queryExample(fluxQuery) {
log('\n*** QUERY ***')
const queryApi = influxDB.getQueryApi(org)
queryApi.queryRows(fluxQuery, {
next(row, tableMeta) {
const o = tableMeta.toObject(row)
if (o.example){
// custom output for example query
log(
`${o._time} ${o._measurement} in '${o.location}' (${o.example}): ${o._field}=${o._value}`
)
} else {
// default output
log(JSON.stringify(o, null, 2))
}
},
error(error) {
log('QUERY FAILED', error)
},
complete() {
log('QUERY FINISHED')
},
})
}
Метод getQueryApi создает QueryApi для предоставленного org. Метод queryRows выполняет запрос и возвращает строки в аннотированном csv, где console.log(o)
дает:
{result: "_result", table: "0", _start: "1970-01-01T00:00:00Z", _stop: "2020-04-03T20:39:23.761184Z", _time: "2020-04-03T18:31:33.95Z", …}
result: "_result"
table: "0"
_start: "1970-01-01T00:00:00Z"
_stop: "2020-04-03T20:39:23.761184Z"
_time: "2020-04-03T18:31:33.95Z"
_value: 29.9
_field: "value"
_measurement: "temperature"
example: "index.html"
location: "browser"
__proto__: Object
InfluxDB v1.8 или выше
Применяется тот же пример выше, но URL-адрес подключения другой. Для конечной точки запроса Flux используйте: http://<hostname>:8086/api/v2/query
Проверки здоровья
Мониторинг работоспособности вашего экземпляра базы данных с помощью вашего API — важный шаг в построении конвейера, которому вы можете доверять. Этот пример браузера также включает проверку работоспособности:
const {InfluxDB} = require('@influxdata/influxdb-client') const {HealthAPI} = require('@influxdata/influxdb-client-apis') const {url, token} = require('./env')
console.log('*** HEALTH CHECK ***') const influxDB = new InfluxDB({url, token}) const healthAPI = new HealthAPI(influxDB)
healthAPI .getHealth() .then((result /* : HealthCheck */) => { console.log(JSON.stringify(result, null, 2)) console.log('\nFinished SUCCESS') }) .catch(error => { console.error(error) console.log('\nFinished ERROR') })
Чтобы получить работоспособность экземпляра, вам необходимо:
- Создайте новый объект InfluxDB
- Создайте HealthAPI из объекта InfluxDB.
- Используйте метод getHealth для возврата статуса API (подробнее см. Документацию по API)
Онбординг
Наконец, эта демонстрация включает пример адаптации пользователя. Простая и быстрая адаптация пользователей позволяет разработчикам приложений обеспечить низкий барьер для пользователей, желающих получить доступ к своим данным временных рядов. Чтобы реализовать инструмент адаптации, вы должны указать имя пользователя и пароль для ./env.
const setupApi = new SetupAPI(new InfluxDB({url}))
setupApi .getSetup() .then(async ({allowed}) => { if (allowed) { await setupApi.postSetup({ body: { org, bucket, username, password, token, }, }) console.log(`InfluxDB '${url}' is now onboarded.`) } else { console.log(`InfluxDB '${url}' has been already onboarded.`) } console.log('\nFinished SUCCESS') }) .catch(error => { console.error(error) console.log('\nFinished ERROR') })
Как и в случае с проверкой работоспособности, чтобы зарегистрировать нового пользователя, вам необходимо:
- Создайте новый объект InfluxDB
- Создайте SetupAPI из объекта InfluxDB.
- Используйте метод getSetup для настройки начального пользователя, организации и корзины.
Заключительные мысли о JavaScript-клиенте InfluxDB v2
Важно отметить, что в дополнение к средам браузера также поддерживаются среды Node. Кроме того, я хочу поделиться некоторыми дополнительными ресурсами, которые могут быть полезны разработчикам JavaScript. Если вам нравится пользовательский интерфейс InfluxDB и вы хотите воспользоваться сложными алгоритмами визуализации данных временных рядов, я рекомендую проверить Giraffe и Clockface. Giraffe — это библиотека визуализации на основе React с открытым исходным кодом, используемая для реализации пользовательского интерфейса (UI) InfluxDB Cloud 2.0. Clockface — это набор пользовательского интерфейса React и Typescript с открытым исходным кодом для создания пользовательского интерфейса InfluxDB v2 и других приложений визуализации временных рядов.
Я надеюсь, что это руководство поможет вам начать знакомство с JavaScript и InfluxDB. Как всегда, я хотел бы услышать ваши мысли и ответить на любые ваши вопросы. Пожалуйста, разместите их на нашем сайте сообщества или на канале Slack.