可觀測性后端【免費(fèi)下載鏈接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.項(xiàng)目地址https://gitcode.com/gh_mirrors/hi/highlight點(diǎn)擊查看免費(fèi)下載highlight.io 的 Grafana 數(shù)據(jù)源插件倉庫目錄 sdk/highlightinc-highlight-datasource是一個基于 Grafana 官方腳手架生成的 TypeScript Go 混合插件其根目錄下的.config/目錄集中存放了 ESLint、Prettier、Jest、TypeScript 與 Webpack 等工具的默認(rèn)構(gòu)建配置。本文以該目錄自帶的說明文檔sdk/highlightinc-highlight-datasource/.config/README.md為主線逐項(xiàng)講解如何在插件根目錄安全地擴(kuò)展這些配置并結(jié)合倉庫中的真實(shí)實(shí)現(xiàn)jest.config.js、tsconfig.json、package.json、docker-compose.yaml以及前后端源碼進(jìn)行印證。讀完本文你將掌握一套可復(fù)用的 Grafana 插件構(gòu)建配置擴(kuò)展方法并能定位 highlight.io 數(shù)據(jù)源插件中每一項(xiàng)配置的實(shí)際作用。認(rèn)識.config目錄自動生成、只讀優(yōu)先.config/目錄由 Grafana 腳手架scaffolding自動生成其定位是“默認(rèn)構(gòu)建配置”專門用于支撐插件的開發(fā)、測試與構(gòu)建流程。官方對它的使用邊界給出了兩條明確建議不要直接修改.config/目錄中的任何文件。這些文件會隨腳手架升級而更新手工改動會在后續(xù)同步時產(chǎn)生沖突或被覆蓋如需定制應(yīng)在插件項(xiàng)目根目錄新建對應(yīng)的配置文件并通過extends/ 合并的方式繼承默認(rèn)配置把自定義邏輯與默認(rèn)配置解耦。這條“自動生成、不直接改、根目錄覆蓋”的約定正是本文全部擴(kuò)展做法的底層原則。在 highlight.io 數(shù)據(jù)源插件倉庫中可以找到與該約定一一對應(yīng)的真實(shí)產(chǎn)物根目錄下的 jest.config.js、jest-setup.js、tsconfig.json 都是典型的“繼承.config/默認(rèn)配置”的文件。擴(kuò)展 ESLint 配置Grafana 腳手架提供了一套基于grafana/eslint-config的默認(rèn) ESLint 規(guī)則見 package.json 中的grafana/eslint-config依賴。要擴(kuò)展它只需編輯插件項(xiàng)目根目錄下的.eslintrc文件用extends指向.config/.eslintrc即可{ extends: ./.config/.eslintrc, rules: { react/prop-types: off } }上面的例子演示了如何在保留 Grafana 全部默認(rèn)規(guī)則的同時關(guān)閉react/prop-types這條規(guī)則。其他規(guī)則的增刪改均可照此辦理——你只需維護(hù)根目錄的.eslintrc.config/目錄保持原樣。與倉庫腳本的配合擴(kuò)展后的 ESLint 配置會通過以下 npm script 生效見 package.jsonlint: eslint src --ext ts,tsx --report-unused-disable-directives, lint:fix: yarn lint -- --fix注意 lint 范圍是src目錄前端源碼插件后端為 Go 實(shí)現(xiàn)其代碼規(guī)范由 Go 工具鏈如go vet、gofmt負(fù)責(zé)不在 ESLint 管轄范圍內(nèi)。擴(kuò)展 Prettier 配置與 ESLint 類似Prettier 的默認(rèn)配置位于.config/.prettierrc.js。在插件項(xiàng)目根目錄新建.prettierrc.js先展開默認(rèn)配置再覆蓋你需要的選項(xiàng)module.exports { // Prettier configuration provided by Grafana scaffolding ...require(./.config/.prettierrc.js), semi: false, };這里通過對象展開把 Grafana 提供的默認(rèn)配置完整繼承下來僅把semi行尾分號改為false。由于默認(rèn)配置和自定義配置分處兩個文件后續(xù) Grafana 腳手架升級默認(rèn)配置時你的自定義項(xiàng)不會丟失。擴(kuò)展 Jest 配置插件的單元測試基于 Jest。與 Jest 相關(guān)的配置分散在兩個根目錄文件中各自職責(zé)如下jest-setup.js在每個測試文件執(zhí)行之前運(yùn)行用于初始化 Jest DOMtesting library 依賴并應(yīng)用必要的 polyfilljest.config.js主配置入口負(fù)責(zé)繼承 Grafana 推薦的 Jest 設(shè)置。在 highlight.io 數(shù)據(jù)源插件倉庫中這兩個文件都有真實(shí)的極簡實(shí)現(xiàn)jest-setup.js 僅做一件事——引入腳手架的 setup// Jest setup provided by Grafana scaffolding import ./.config/jest-setup;jest.config.js 在繼承默認(rèn)配置的同時強(qiáng)制將時區(qū)固定為 UTC以保證快照snapshot測試在不同本地時區(qū)下結(jié)果一致// force timezone to UTC to allow tests to work regardless of local timezone // generally used by snapshots, but can affect specific tests process.env.TZ UTC; module.exports { // Jest configuration provided by Grafana scaffolding ...require(./.config/jest.config), };ESM 報錯的處理高頻坑點(diǎn)使用 Jest 時一個常見問題是當(dāng)import一個只提供 ESM 構(gòu)建的 npm 包時Jest 會報SyntaxError: Cannot use import statement outside a module。原因在于 Jest 默認(rèn)只轉(zhuǎn)換node_modules之外的源碼而 Grafana 的腳手架配置內(nèi)部維護(hù)了一份已知的“需要轉(zhuǎn)換的 ESM 包”清單grafanaESModules。解決方法是給 Jest 的transformIgnorePatterns傳入這份清單并在需要時追加額外的包名。腳手架說明文檔給出的擴(kuò)展寫法如下process.env.TZ UTC; const { grafanaESModules, nodeModulesToTransform } require(./config/jest/utils); module.exports { // Jest configuration provided by Grafana ...require(./.config/jest.config), // Inform jest to only transform specific node_module packages. transformIgnorePatterns: [nodeModulesToTransform([...grafanaESModules, packageName])], };其中nodeModulesToTransform([...])會把“已知 ESM 包 你新追加的包名”轉(zhuǎn)換為 jest 的正則白名單其余node_modules仍按默認(rèn)策略跳過轉(zhuǎn)換。在 highlight.io 數(shù)據(jù)源插件中emotion/css、grafana/ui等現(xiàn)代依賴都是典型的需要納入此白名單的對象。順帶一提該插件的 package.json 還引入了swc/jest與swc/core作為測試轉(zhuǎn)換器配合babel/core處理 TS/TSX 編譯這也是 Grafana 10.x 時代腳手架默認(rèn)的轉(zhuǎn)換鏈路。擴(kuò)展 TypeScript 配置TypeScript 的默認(rèn)配置位于.config/tsconfig.json。在插件項(xiàng)目根目錄編輯tsconfig.json通過extends繼承默認(rèn)配置并用compilerOptions覆蓋需要的選項(xiàng){ extends: ./.config/tsconfig.json, compilerOptions: { preserveConstEnums: true } }倉庫中真實(shí)的 tsconfig.json 正是這一模式的標(biāo)準(zhǔn)示范——繼承.config/tsconfig.json只補(bǔ)充jsx: react和esModuleInterop: true{ compilerOptions: { jsx: react, esModuleInterop: true }, extends: ./.config/tsconfig.json }jsx: react讓 TypeScript 以經(jīng)典 React 運(yùn)行時編譯 JSX與項(xiàng)目前端使用 React 19 的配置一致見 package.json 的react依賴esModuleInterop: true允許import React from react這類默認(rèn)導(dǎo)入寫法是 Grafana 前端代碼的常見約定。插件提供了typecheck: tsc --noEmit腳本見 package.json你可以隨時用它驗(yàn)證擴(kuò)展后的 TypeScript 配置是否正確。擴(kuò)展 Webpack 配置三步走Webpack 是插件的核心打包器默認(rèn)配置位于.config/webpack/webpack.config。擴(kuò)展它需要三步每一步都有明確的文件與命令要求。第 1 步新建自定義 Webpack 配置文件在插件項(xiàng)目根目錄新建webpack.config.ts作為自定義配置的宿主// webpack.config.ts import type { Configuration } from webpack; import { merge } from webpack-merge; import grafanaConfig from ./.config/webpack/webpack.config; const config async (env): PromiseConfiguration { const baseConfig await grafanaConfig(env); return merge(baseConfig, { // Add custom config here... output: { asyncChunks: true, }, }); }; export default config;這里用webpack-merge將 Grafana 的基礎(chǔ)配置與自定義配置深度合并。示例中開啟了output.asyncChunks你可以在此位置追加任何 webpack 配置項(xiàng)如自定義 loader、alias 或插件。第 2 步更新package.json的構(gòu)建腳本要讓 webpack 使用新配置需要把 package.json 中的build與dev腳本從指向.config/改為指向根目錄的新文件build生產(chǎn)構(gòu)建:-build: webpack -c ./.config/webpack/webpack.config.ts --env production, build: webpack -c ./webpack.config.ts --env production,dev開發(fā)監(jiān)聽模式:-dev: webpack -w -c ./.config/webpack/webpack.config.ts --env development, dev: webpack -w -c ./webpack.config.ts --env development,-c指定配置文件--env production/--env development把環(huán)境標(biāo)識透傳給配置函數(shù)即第 1 步中的env參數(shù)-w啟用 watch 模式源碼變更后自動重新打包。倉庫當(dāng)前 package.json 中的build、dev腳本即默認(rèn)指向.config/webpack/webpack.config.ts遵循上述步驟即可無縫切換到自定義配置。第 3 步驗(yàn)證產(chǎn)物構(gòu)建完成后打包結(jié)果輸出到dist/目錄其中包含后端可執(zhí)行文件gpx_highlightinc_highlight_datasource該名稱由 plugin.json 中的executable字段聲明。dist/目錄會被 docker-compose.yaml 掛載進(jìn) Grafana 容器因此修改 Webpack 配置后只需重建并重啟容器即可在 Grafana 中看到新的插件行為。配置 Grafana Docker 鏡像腳手架的所有 Docker 相關(guān)命令默認(rèn)使用grafana-enterprise鏡像。如果需要覆蓋可在docker-compose.yaml的grafana服務(wù)構(gòu)建塊中增加grafana_image構(gòu)建參數(shù)version: 3.7 services: grafana: container_name: myorg-basic-app build: context: ./.config args: grafana_version: ${GRAFANA_VERSION:-9.1.2} grafana_image: ${GRAFANA_IMAGE:-grafana}grafana_image構(gòu)建參數(shù)從環(huán)境變量GRAFANA_IMAGE讀取默認(rèn)值為grafana社區(qū)版grafana_version同理從GRAFANA_VERSION讀取默認(rèn)值示例中為9.1.2運(yùn)行時通過GRAFANA_IMAGExxx docker-compose up --build即可臨時切換鏡像適合在需要測試不同 Grafana 版本或企業(yè)版/社區(qū)版差異的場景下使用。倉庫真實(shí)的 docker-compose.yaml 已經(jīng)遵循了這一模式并把默認(rèn) Grafana 版本定為10.1.0與 plugin.json 中聲明的grafanaDependency: 10.1.0相匹配。它還在extra_hosts中配置了host.docker.internal:host-gateway并把dist/、provisioning/、dashboards/分別掛載到容器的插件目錄、provisioning 目錄與儀表盤目錄端口映射為3001:3000services: grafana: container_name: highlightinc-highlight-datasource extra_hosts: - host.docker.internal:host-gateway platform: linux/amd64 build: context: ./.config args: grafana_image: ${GRAFANA_IMAGE:-grafana} grafana_version: ${GRAFANA_VERSION:-10.1.0} ports: - 3001:3000/tcp volumes: - ./dist:/var/lib/grafana/plugins/highlightinc-highlight-datasource - ./provisioning:/etc/grafana/provisioning - ./dashboards:/var/lib/grafana/dashboards - ./grafana/data:/var/lib/grafana源碼印證構(gòu)建配置之外的插件本體理解構(gòu)建配置的價值在于它能支撐起插件真正的功能。highlight.io 數(shù)據(jù)源插件的運(yùn)行鏈路恰好與上面每一層配置一一對應(yīng)可作為擴(kuò)展配置后的驗(yàn)證入口1. 插件能力聲明plugin.json{ type: datasource, name: Highlight.io, id: highlightinc-highlight-datasource, backend: true, executable: gpx_highlightinc_highlight_datasource, alerting: true, metrics: true, logs: true }backend: true說明插件同時包含 Go 后端進(jìn)程由 Webpack 之外的 Mage 構(gòu)建產(chǎn)出的gpx_*可執(zhí)行文件alerting/metrics/logs聲明了它支持告警、指標(biāo)與日志數(shù)據(jù)源能力——這正是Metrics、LogLines等查詢類型的來源。2. 前端查詢構(gòu)造src/datasource.ts前端繼承 Grafana 的DataSourceWithBackend內(nèi)置的tableOptions把查詢資源限定為traces、logs、errors、sessions四種metricOptions定義了Count、CountDistinct、Min、Avg、P50、P90、P95、P99、Max、Sum、None等聚合函數(shù)且每個函數(shù)標(biāo)注了可用的資源表getDefaultQuery()則給出默認(rèn)查詢參數(shù)如bucketCount: 50、limit: 10、默認(rèn)按Timestamp分桶。TypeScript 配置上一節(jié)擴(kuò)展的tsconfig.json正是為編譯這些前端源碼服務(wù)的。3. 后端 GraphQL 執(zhí)行pkg/plugin/datasource.go后端NewDatasource在ClientId非空時使用 OAuth2 客戶端憑證模式clientcredentials.Config自動換取訪問令牌否則直接使用默認(rèn) HTTP 客戶端——這對應(yīng)了配置面板中“云托管填 Client ID/Secret、自托管留空”的行為。查詢分發(fā)邏輯query()函數(shù)在Metric None時走日志行查詢queryLogLines返回帶FrameTypeLogLines元數(shù)據(jù)的日志幀否則走指標(biāo)查詢queryMetrics通過metricsGraphQL 查詢拉取分桶指標(biāo)按Timestamp或自定義bucket_by鍵構(gòu)造時序/直方圖幀。CheckHealth通過一次traces_metrics計(jì)數(shù)查詢驗(yàn)證連接對應(yīng)配置頁的Save test按鈕。4. 預(yù)置數(shù)據(jù)源配置provisioning/datasources/datasource.yamlapiVersion: 1 datasources: - name: Highlight.io type: highlightinc-highlight-datasource jsonData: clientID: projectID: 1344 tokenURL: https://pri.highlight.io/oauth/token backendURL: https://pri.highlight.io version: 1 editable: true這是開箱即用的演示配置projectID: 1344指向 highlight.io 官方演示項(xiàng)目backendURL與tokenURL指向云托管后端https://pri.highlight.ioclientID留空演示項(xiàng)目無需 OAuth。四個 jsonData 字段與前端 ConfigEditor.tsx 的輸入框一一對應(yīng)其中clientSecret作為安全字段寫入secureJsonData僅在后端解密使用。擴(kuò)展配置的注意事項(xiàng)與常見問題綜合以上內(nèi)容擴(kuò)展構(gòu)建配置時有幾點(diǎn)需要格外留意自擔(dān)風(fēng)險.config/說明文檔明確提示擴(kuò)展基礎(chǔ)配置屬于“自擔(dān)風(fēng)險”操作配置不當(dāng)可能導(dǎo)致項(xiàng)目構(gòu)建、測試或與 Grafana 的集成出現(xiàn)問題永遠(yuǎn)通過根目錄文件覆蓋而非修改.config/無論是.eslintrc、.prettierrc.js、jest.config.js還是tsconfig.json、webpack.config.ts一律在插件根目錄新建或修改用extends、對象展開或webpack-merge繼承默認(rèn)配置版本一致性本插件的構(gòu)建鏈路依賴node 20見 package.json 的engines字段且 Grafana 依賴版本為10.1.0擴(kuò)展 Webpack 或升級腳手架時應(yīng)同時核對這兩項(xiàng)約束Go 與 TS 雙棧分工插件是 TypeScript前端 Go后端混合項(xiàng)目ESLint/Prettier/Jest/TypeScript/Webpack 配置只作用于src/前端部分后端由 Go 工具鏈管理二者構(gòu)建流程相互獨(dú)立但最終統(tǒng)一打包進(jìn)插件目錄。遵循“繼承默認(rèn)、根目錄覆蓋、自擔(dān)風(fēng)險”的原則你可以在不破壞 Grafana 腳手架可升級性的前提下為 highlight.io 數(shù)據(jù)源插件或其他任何基于 Grafana 腳手架生成的插件定制出一套完全符合團(tuán)隊(duì)規(guī)范的構(gòu)建、測試與開發(fā)環(huán)境。贊分享可觀測性后端【免費(fèi)下載鏈接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.項(xiàng)目地址https://gitcode.com/gh_mirrors/hi/highlight點(diǎn)擊查看免費(fèi)下載相關(guān)推薦在 Grafana 中接入 highlight.io數(shù)據(jù)源插件的安裝、可視化查詢與告警配置指南在 Grafana 中接入 highlight.io數(shù)據(jù)源插件的安裝、可視化查詢與告警配置指南 本文講解如何通過 highlight.io 官方 Grafan可觀測性后端使用 skpm 構(gòu)建 react-sketchapp 插件從腳手架到自定義構(gòu)建配置的完整指南使用 skpm 構(gòu)建 react sketchapp 插件從腳手架到自定義構(gòu)建配置的完整指南 導(dǎo)讀 本文以 react sketchapp 官方指南 docs開發(fā)工具前端highlight.io Grafana 數(shù)據(jù)源接入指南安裝、配置與自托管 OAuth 認(rèn)證設(shè)置highlight.io Grafana 數(shù)據(jù)源接入指南安裝、配置與自托管 OAuth 認(rèn)證設(shè)置 highlight.io 提供官方 Grafana 數(shù)據(jù)源插可觀測性后端上一篇dxwrapper 完整指南三步讓老游戲在 Windows 10/11 上正常運(yùn)行下一篇Squirrel-RIFE 免費(fèi)AI視頻補(bǔ)幀教程24fps升60fps實(shí)操創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考