{"id":17679930,"url":"https://github.com/autometrics-dev/autometrics-ts","last_synced_at":"2025-04-07T17:07:46.456Z","repository":{"id":66985691,"uuid":"592745011","full_name":"autometrics-dev/autometrics-ts","owner":"autometrics-dev","description":"Easily add metrics to your system – and actually understand them using automatically customized Prometheus queries","archived":false,"fork":false,"pushed_at":"2024-02-28T10:08:56.000Z","size":6942,"stargazers_count":130,"open_issues_count":3,"forks_count":7,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-04-14T10:36:49.097Z","etag":null,"topics":["metrics","monitoring","observability","opentelemetry","prometheus","telemetry","typescript"],"latest_commit_sha":null,"homepage":"https://autometrics.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/autometrics-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-24T12:51:17.000Z","updated_at":"2024-06-21T02:37:11.051Z","dependencies_parsed_at":"2024-01-16T12:47:13.159Z","dependency_job_id":"1e2b23c0-871e-4d90-848d-760e68923db7","html_url":"https://github.com/autometrics-dev/autometrics-ts","commit_stats":{"total_commits":116,"total_committers":6,"mean_commits":"19.333333333333332","dds":0.4568965517241379,"last_synced_commit":"06ff7739ccd82f2a1d382f3b0d62c906ea72956a"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/autometrics-dev%2Fautometrics-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/autometrics-dev%2Fautometrics-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/autometrics-dev%2Fautometrics-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/autometrics-dev%2Fautometrics-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/autometrics-dev","download_url":"https://codeload.github.com/autometrics-dev/autometrics-ts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247694875,"owners_count":20980733,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["metrics","monitoring","observability","opentelemetry","prometheus","telemetry","typescript"],"created_at":"2024-10-24T09:04:44.885Z","updated_at":"2025-04-07T17:07:46.427Z","avatar_url":"https://github.com/autometrics-dev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![GitHub_headerImage](https://user-images.githubusercontent.com/3262610/221191767-73b8a8d9-9f8b-440e-8ab6-75cb3c82f2bc.png)\n\n\u003cdiv align=\"center\"\u003e\n\u003ch1\u003eAutometrics\u003c/h1\u003e\n\u003ca href=\"https://github.com/autometrics-dev/autometrics-ts/actions?query=branch%3Amain\"\u003e\u003cimg src=\"https://github.com/autometrics-dev/autometrics-ts/actions/workflows/ci.yml/badge.svg?event=push\u0026branch=main\" alt=\"Autometrics CI status\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://opensource.org/licenses/MIT\" rel=\"nofollow\"\u003e\u003cimg src=\"https://img.shields.io/npm/l/@autometrics/autometrics\" alt=\"License\"\u003e\u003c/a\u003e\n\u003ca href=\"https://discord.gg/MJr7pYzZQ4\" rel=\"nofollow\"\u003e\u003cimg src=\"https://img.shields.io/discord/950489382626951178?label=Discord\u0026logo=discord\u0026logoColor=white\" alt=\"discord server\"\u003e\u003c/a\u003e\n\u003c/div\u003e\n\n\u003chr /\u003e\n\nMetrics are a powerful and cost-efficient tool for understanding the health and performance of your code in production. But it's hard to decide what metrics to track and even harder to write queries to understand the data.\n\nAutometrics provides a wrapper function and decorator to instrument functions, classes, and methods with the most useful metrics: request rate, error rate, and latency. It standardizes these metrics and then generates powerful Prometheus queries based on your function details to help you quickly identify and debug issues in production.\n\n[Learn more about Autometrics at autometrics.dev](https://autometrics.dev/).\n\n## Benefits\n\n- ✨ `autometrics()` wrapper / `@Autometrics()` decorator instruments any function or class method to track its most useful metrics\n- 🌳 Works in Deno, NodeJS and browser environments [(*)](#known-issues)\n- 💡 Writes Prometheus queries so you can understand the data generated without knowing PromQL\n- 🔗 Injects links to live Prometheus charts directly into each function's doc\n- 🔍 Helps you to [identify commits](https://docs.autometrics.dev/typescript/adding-version-information) that introduced errors or increased latency\n- 📊 [Grafana dashboards](https://github.com/autometrics-dev/autometrics-shared#dashboards) work out of the box and visualize the performance of instrumented functions \u0026 SLOs\n- ⚡ Minimal runtime overhead\n\n### Known issues\n\n- Pushing metrics from client-side and FaaS environments is currently experimental.\n\n## Advanced Features\n- 🚨 Allows you to [define alerts](https://docs.autometrics.dev/typescript/adding-alerts-and-slos) using SLO best practices directly in your source code comments\n\n## Example\n\n```ts\nimport { autometrics } from \"@autometrics/autometrics\";\n\nconst createUserWithMetrics = autometrics(async function createUser(payload: User) {\n  // ...\n});\n\ncreateUserWithMetrics();\n```\n\n![AutometricsTS demo](./assets/autometrics-ts-demo.gif)\n\n## Quickstart with Node.js and Prometheus\n\n(See the [recipes](#recipes) below for other setup scenarios.)\n\n1. **Install the library**\n\n```sh\nnpm install @autometrics/autometrics @autometrics/exporter-prometheus\n# or\nyarn add @autometrics/autometrics @autometrics/exporter-prometheus\n# or\npnpm add @autometrics/autometrics @autometrics/exporter-prometheus\n```\n\n2. **Instrument your code using the `autometrics` wrapper or `Autometrics` decorator**\n\n```ts\nimport { autometrics } from \"@autometrics/autometrics\";\n\nconst createUserWithMetrics = autometrics(async function createUser(payload: User) {\n  // ...\n});\n\ncreateUserWithMetrics();\n```\n\n```ts\nimport { Autometrics } from \"@autometrics/autometrics\";\n\nclass User {\n  @Autometrics()\n  async createUser(payload: User) {\n    // ...\n  }\n}\n```\n\n3. **Call `init()` to set up a Prometheus scrape endpoint**\n\nThis endpoint will serve to export the metrics from your application and allows\nthem to be scraped by Prometheus.\n\n```ts\nimport { init } from \"@autometrics/exporter-prometheus\";\n\ninit(); // starts the webserver with the `/metrics` endpoint on port 9464\n```\n\n3. **Run Prometheus locally to validate and preview the data**\n\nYou can use the open source Autometrics CLI to run automatically configured Prometheus locally to see the metrics that will be registered by the change. See the [Autometrics CLI docs](https://docs.autometrics.dev/local-development#getting-started-with-am) for more information.\n\nor you can configure Prometheus manually:\n\n```yaml\nscrape_configs:\n  - job_name: my-app\n    metrics_path: /metrics # The default path for the Autometrics Prometheus exporter\n    static_configs:\n      - targets: ['localhost:9464'] # The default port for the Autometrics Prometheus exporter\n    scrape_interval: 200ms\n    # For a real deployment, you would want the scrape interval to be\n    # longer but for testing, you want the data to show up quickly\n```\n\n[See the docs](https://docs.autometrics.dev/configuring-prometheus/local) for more Prometheus configurations.\n\n4. **Install the IDE extension**\n\nIn order to get charts in VSCode, download the [Autometrics VSCode extension](https://marketplace.visualstudio.com/items?itemName=Fiberplane.autometrics).\n\n\u003cdetails\u003e\n    \u003csummary\u003e\n    If you're on any other IDE you can install and add the TypeScript plugin\n    directly:\n    \u003c/summary\u003e\n\n```bash\nnpm install --save-dev @autometrics/typescript-plugin\n```\n\nAdd the language service plugin to the `tsconfig.json` file:\n\n```json\n{\n  \"compilerOptions\": {\n    \"plugins\": [\n      {\n        \"name\": \"@autometrics/typescript-plugin\",\n        \"prometheusUrl\": \"\"\n      }\n    ]\n  }\n}\n```\n\n\u003c/details\u003e\n\n## [Documentation](https://docs.autometrics.dev/typescript/quickstart)\n\n## [API Reference](./packages/lib/reference/README.md)\n\n## Recipes\n\nBelow are different recipes for using Autometrics with a server-side setup and\nedge/client-side setups. If you would like to see examples with specific\nframeworks, please have a look at the [examples/](examples/) directory.\n\n### Server-side example with Prometheus\n\n#### Installation\n\n```sh\nnpm install @autometrics/autometrics @autometrics/exporter-prometheus\n# or\nyarn add @autometrics/autometrics @autometrics/exporter-prometheus\n# or\npnpm add @autometrics/autometrics @autometrics/exporter-prometheus\n```\n\n#### Usage\n\n1. Anywhere in your source code:\n\n```ts\nimport { autometrics } from \"@autometrics/autometrics\";\nimport { init } from \"@autometrics/exporter-prometheus\";\n\ninit(); // starts the webserver with the `/metrics` endpoint on port 9464\n\nasync function createUserRaw(payload: User) {\n  // ...\n}\n\nconst createUser = autometrics(createUserRaw);\n   // ^ instrumented function\n```\n\n### Recipe: Edge/Client-side example with a Prometheus Push Gateway\n\n#### Installation\n\n```sh\nnpm install @autometrics/autometrics @autometrics/exporter-prometheus-push-gateway\n# or\nyarn add @autometrics/autometrics @autometrics/exporter-prometheus-push-gateway\n# or\npnpm add @autometrics/autometrics @autometrics/exporter-prometheus-push-gateway\n```\n\n#### Usage\n\n1. Anywhere in your source code:\n\n```ts\nimport { autometrics } from \"@autometrics/autometrics\";\nimport { init } from \"@autometrics/exporter-prometheus-push-gateway\";\n\ninit({ url: \"https://\u003cyour-push-gateway\u003e\" });\n\nasync function createUserRaw(payload: User) {\n  // ...\n}\n\nconst createUser = autometrics(createUserRaw);\n   // ^ instrumented function\n```\n\n### Recipe: Edge/Client-side example with the OpenTelemetry Collector\n\n#### Installation\n\n```sh\nnpm install @autometrics/autometrics @autometrics/exporter-otlp-http\n# or\nyarn add @autometrics/autometrics @autometrics/exporter-otlp-http\n# or\npnpm add @autometrics/autometrics @autometrics/exporter-otlp-http\n```\n\n#### Usage\n\n1. Anywhere in your source code:\n\n```ts\nimport { autometrics } from \"@autometrics/autometrics\";\nimport { init } from \"@autometrics/exporter-otlp-http\";\n\ninit({ url: \"https://\u003cyour-otel-collector\u003e\" });\n\nasync function createUserRaw(payload: User) {\n  // ...\n}\n\nconst createUser = autometrics(createUserRaw);\n   // ^ instrumented function\n```\n\n## Contributing\n\nIssues, feature suggestions, and pull requests are very welcome!\n\nIf you are interested in getting involved:\n- Join the conversation on [Discord](https://discord.gg/9eqGEs56UB)\n- Ask questions and share ideas in the [Github Discussions](https://github.com/orgs/autometrics-dev/discussions)\n- Take a look at the overall [Autometrics Project Roadmap](https://github.com/orgs/autometrics-dev/projects/1)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fautometrics-dev%2Fautometrics-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fautometrics-dev%2Fautometrics-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fautometrics-dev%2Fautometrics-ts/lists"}