{"_id":"@azumaxoid/lcp-performance-tracer","_rev":"2-fbad2618022722425e6c23b4b76e14e5","name":"@azumaxoid/lcp-performance-tracer","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@azumaxoid/lcp-performance-tracer","version":"1.0.0","keywords":["lcp","performance","monitoring","new-relic","web-vitals","typescript"],"author":{"name":"Azumaxoid"},"license":"MIT","_id":"@azumaxoid/lcp-performance-tracer@1.0.0","maintainers":[{"name":"azumaxoid","email":"azumax.android@gmail.com"}],"homepage":"https://github.com/Azumaxoid/nr-browser-resource-tracer#readme","bugs":{"url":"https://github.com/Azumaxoid/nr-browser-resource-tracer/issues"},"dist":{"shasum":"77cc51342c8c44828f1b197103734ba31abc1abf","tarball":"https://registry.npmjs.org/@azumaxoid/lcp-performance-tracer/-/lcp-performance-tracer-1.0.0.tgz","fileCount":35,"integrity":"sha512-8uEYylawOVToCuNAkNJUbJsOmIYDG4mhiE7mv0kPE+GJOmOtxFxIzIL8uhtRVakxsWhnCUvbfsydplPMdf9N1A==","signatures":[{"sig":"MEUCIQDe27lWw9HjuCwHvwBIw4WNfyZJi1Lu9534JvfHOvZ8TgIgZTgcrbd2CNYLgLVgzIc0/pDiwAqeEsWtiJQqtzzQsNM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":64714},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.esm.js","engines":{"node":">=14.0.0"},"gitHead":"905a591212c7852dfc5d892c63ce2ef563ff3c77","scripts":{"lint":"eslint src/**/*.ts","test":"jest","build":"npm run clean && npm run build:cjs && npm run build:esm && npm run build:types","clean":"rm -rf dist","build:cjs":"tsc -p tsconfig.cjs.json","build:esm":"tsc -p tsconfig.esm.json","typecheck":"tsc --noEmit","test:watch":"jest --watch","build:types":"tsc -p tsconfig.types.json","test:coverage":"jest --coverage","prepublishOnly":"npm run build && npm run test"},"_npmUser":{"name":"azumaxoid","email":"azumax.android@gmail.com"},"repository":{"url":"git+https://github.com/Azumaxoid/nr-browser-resource-tracer.git","type":"git"},"_npmVersion":"11.3.0","description":"A TypeScript library for tracking LCP performance and sending trace data to New Relic","directories":{},"_nodeVersion":"24.1.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","eslint":"^8.51.0","ts-jest":"^29.1.1","typescript":"^5.2.2","@types/jest":"^29.5.5","@types/node":"^20.8.0","jest-environment-jsdom":"^29.7.0","@typescript-eslint/parser":"^6.7.5","@typescript-eslint/eslint-plugin":"^6.7.5"},"_npmOperationalInternal":{"tmp":"tmp/lcp-performance-tracer_1.0.0_1755877345854_0.5613593044496177","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@azumaxoid/lcp-performance-tracer","version":"1.0.1","description":"A TypeScript library for tracking LCP performance and sending trace data to New Relic","main":"dist/index.js","module":"dist/index.esm.js","types":"dist/index.d.ts","scripts":{"build":"npm run clean && npm run build:cjs && npm run build:esm && npm run build:types && npm run build:standalone","build:cjs":"tsc -p tsconfig.cjs.json","build:esm":"tsc -p tsconfig.esm.json","build:types":"tsc -p tsconfig.types.json","build:standalone":"rollup -c rollup.config.js","build:standalone:watch":"rollup -c rollup.config.js --watch","analyze:bundle":"npm run build:standalone && ls -lh dist/standalone/*.js | awk '{print $9, $5}'","clean":"rm -rf dist","test":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage","lint":"eslint src/**/*.ts","typecheck":"tsc --noEmit","prepublishOnly":"npm run build && npm run test"},"keywords":["lcp","performance","monitoring","new-relic","web-vitals","typescript"],"author":{"name":"Azumaxoid"},"license":"MIT","devDependencies":{"@rollup/plugin-commonjs":"^28.0.6","@rollup/plugin-node-resolve":"^16.0.1","@rollup/plugin-terser":"^0.4.4","@rollup/plugin-typescript":"^12.1.4","@types/jest":"^29.5.5","@types/node":"^20.8.0","@typescript-eslint/eslint-plugin":"^6.7.5","@typescript-eslint/parser":"^6.7.5","eslint":"^8.51.0","jest":"^29.7.0","jest-environment-jsdom":"^29.7.0","rollup":"^2.79.2","rollup-plugin-sizes":"^1.1.0","rollup-plugin-terser":"^7.0.2","ts-jest":"^29.1.1","tslib":"^2.8.1","typescript":"^5.2.2"},"engines":{"node":">=14.0.0"},"repository":{"type":"git","url":"git+https://github.com/Azumaxoid/nr-browser-resource-tracer.git"},"bugs":{"url":"https://github.com/Azumaxoid/nr-browser-resource-tracer/issues"},"homepage":"https://github.com/Azumaxoid/nr-browser-resource-tracer#readme","publishConfig":{"access":"public"},"_id":"@azumaxoid/lcp-performance-tracer@1.0.1","gitHead":"a0985688e408937c75ec662f4d0d46a79fca60d3","_nodeVersion":"18.20.8","_npmVersion":"10.8.2","dist":{"integrity":"sha512-edhLaeW+I8V7jAeH1yvZvPvzu6d0u5Aq+jYW7mnE7V9kU7Y+5ieDRjvk59Hq/x7mKptC8ZLUO/Sh2h04HbUk5g==","shasum":"3c5a42ce43c9cebc2615c96a54f65018841cb7d2","tarball":"https://registry.npmjs.org/@azumaxoid/lcp-performance-tracer/-/lcp-performance-tracer-1.0.1.tgz","fileCount":43,"unpackedSize":207432,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIF1PS/WduC1JokB7CRJibZ92fLwgjleo3Fz5ZbTG6mhYAiBr6MiUAtMopx1tOYTc0/z0soTHGHatZ7shTGxarxyP9g=="}]},"_npmUser":{"name":"azumaxoid","email":"azumax.android@gmail.com"},"directories":{},"maintainers":[{"name":"azumaxoid","email":"azumax.android@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/lcp-performance-tracer_1.0.1_1756883846146_0.3479730949408222"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-22T15:42:25.789Z","modified":"2025-09-03T07:17:26.507Z","1.0.0":"2025-08-22T15:42:26.066Z","1.0.1":"2025-09-03T07:17:26.335Z"},"bugs":{"url":"https://github.com/Azumaxoid/nr-browser-resource-tracer/issues"},"author":{"name":"Azumaxoid"},"license":"MIT","homepage":"https://github.com/Azumaxoid/nr-browser-resource-tracer#readme","keywords":["lcp","performance","monitoring","new-relic","web-vitals","typescript"],"repository":{"type":"git","url":"git+https://github.com/Azumaxoid/nr-browser-resource-tracer.git"},"description":"A TypeScript library for tracking LCP performance and sending trace data to New Relic","maintainers":[{"name":"azumaxoid","email":"azumax.android@gmail.com"}],"readme":"# LCP Performance Tracer\n\nA TypeScript library for tracking Largest Contentful Paint (LCP) performance metrics and sending trace data to New Relic when LCP exceeds configured thresholds.\n\n## Features\n\n- **Automatic LCP Monitoring**: Tracks LCP using Performance Observer API with fallback support\n- **Resource Timing Collection**: Collects detailed timing data for critical resources\n- **New Relic Integration**: Automatically sends performance data to New Relic when available\n- **Configurable Thresholds**: Set custom LCP thresholds to trigger data collection\n- **Sampling Support**: Control data collection frequency with configurable sampling rates\n- **Zero Dependencies**: Lightweight library with no external dependencies\n- **TypeScript Support**: Full TypeScript definitions included\n\n## Installation\n\n### NPM Installation\n\n```bash\nnpm install @azumaxoid/lcp-performance-tracer\n```\n\n### Standalone Browser Usage\n\nYou can also use the library directly in the browser without any build tools. Simply include the script tag in your HTML:\n\n```html\n<!-- Latest version from GitHub -->\n<script src=\"https://github.com/Azumaxoid/nr-browser-resource-tracer/releases/latest/download/lcp-performance-tracer.min.js\"></script>\n\n<!-- Or specific version -->\n<script src=\"https://github.com/Azumaxoid/nr-browser-resource-tracer/releases/download/v1.0.0/lcp-performance-tracer.min.js\"></script>\n\n<!-- Or from local file -->\n<script src=\"path/to/lcp-performance-tracer.min.js\"></script>\n```\n\n## Quick Start\n\n### Basic Usage (NPM)\n\n```javascript\nimport { LCPPerformanceTracer } from '@azumaxoid/lcp-performance-tracer';\n\n// Create and start the tracer with default settings\nconst tracer = LCPPerformanceTracer.autoStart();\n\n// Or manually control the tracer\nconst tracer = new LCPPerformanceTracer({\n  lcpThreshold: 2500,    // Trigger when LCP > 2.5 seconds\n  samplingRate: 1.0,     // Sample 100% of sessions\n  debug: true,           // Enable debug logging\n  enabled: true,         // Enable the tracer\n  maxResources: 20       // Collect up to 20 resources (default: 10)\n});\n\ntracer.start();\n\n// Stop the tracer when needed\ntracer.stop();\n```\n\n### Standalone Browser Usage\n\nWhen using the standalone browser version, the library is available via the global `LCPPerformanceTracer` object:\n\n```html\n<!DOCTYPE html>\n<html>\n<head>\n  <title>LCP Performance Monitoring</title>\n  <!-- Include the standalone library -->\n  <script src=\"https://github.com/Azumaxoid/nr-browser-resource-tracer/releases/latest/download/lcp-performance-tracer.min.js\"></script>\n</head>\n<body>\n  <h1>My Application</h1>\n  \n  <script>\n    // The library is available as a global object\n    const tracer = new LCPPerformanceTracer.LCPPerformanceTracer({\n      newRelicAccountId: 'your-account-id',\n      newRelicInsertKey: 'your-insert-key',\n      lcpThreshold: 2500,\n      enableDebug: true,\n      collectResourceDetails: true\n    });\n    \n    // Start monitoring\n    tracer.start();\n    \n    // Access other classes if needed\n    const config = new LCPPerformanceTracer.ConfigManager({\n      newRelicAccountId: 'your-account-id',\n      newRelicInsertKey: 'your-insert-key'\n    });\n    \n    // Check library version\n    console.log('LCP Tracer Version:', LCPPerformanceTracer.version);\n  </script>\n</body>\n</html>\n```\n\n### TypeScript Usage\n\n```typescript\nimport { LCPPerformanceTracer, LCPTracerConfig } from 'lcp-performance-tracer';\n\nconst config: LCPTracerConfig = {\n  lcpThreshold: 3000,\n  samplingRate: 0.5,\n  debug: false,\n  enabled: true\n};\n\nconst tracer = new LCPPerformanceTracer(config);\ntracer.start();\n```\n\n## Configuration Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `lcpThreshold` | number | 2500 | LCP threshold in milliseconds. Data is collected when LCP exceeds this value |\n| `samplingRate` | number | 1.0 | Sampling rate between 0 and 1 (e.g., 0.5 = 50% of sessions) |\n| `debug` | boolean | false | Enable debug logging to console |\n| `enabled` | boolean | true | Enable or disable the tracer |\n| `maxResources` | number | 10 | Maximum number of resources to collect (1-100) |\n\n## How It Works\n\n1. **LCP Monitoring**: The library uses the Performance Observer API to monitor LCP events in real-time\n2. **Threshold Detection**: When LCP exceeds the configured threshold, data collection is triggered\n3. **Resource Collection**: Critical resources related to the LCP element are identified and collected\n4. **Data Formatting**: Performance data is formatted into a structured event\n5. **New Relic Reporting**: If New Relic is available, the data is sent using `newrelic.recordCustomEvent`\n\n## Data Collected\n\nWhen LCP exceeds the threshold, the following data is collected and sent:\n\n- **LCP Metrics**: Value, element selector, URL\n- **Navigation Timing**: DOMContentLoaded, load complete, First Contentful Paint\n- **Critical Resources**: All collected resources (configurable with `maxResources`)\n- **Metadata**: User agent, page URL, timestamp, sampling rate\n\n## New Event Types\n\nThe library sends two types of events to New Relic:\n\n1. **`LCPPerformanceTrace`**: Main event with LCP and navigation data\n2. **`LCPResourceTrace`**: Individual events for each collected resource\n\n## New Relic Integration\n\n### Prerequisites\n\nThis library requires New Relic Browser Agent to be already installed and configured in your application. The library will automatically detect and use the global `newrelic` object.\n\n### Event Structure\n\n#### Main LCP Event (`LCPPerformanceTrace`)\n```javascript\n{\n  lcpValue: 3000,\n  lcpElement: 'img#hero-image',\n  lcpUrl: 'https://example.com/image.jpg',\n  domContentLoaded: 500,\n  loadComplete: 1000,\n  firstContentfulPaint: 300,\n  resourceCount: 15,\n  userAgent: 'Mozilla/5.0...',\n  url: 'https://example.com/page',\n  timestamp: 1234567890,\n  samplingRate: 1.0,\n  traceId: 'lcp_1234567890_abc123'\n}\n```\n\n#### Resource Events (`LCPResourceTrace`)\n```javascript\n{\n  traceId: 'lcp_1234567890_abc123',\n  resourceIndex: 0,\n  resourceName: 'https://example.com/hero-image.jpg',\n  resourceDuration: 300,\n  resourceStartTime: 200,\n  resourceTransferSize: 50000,\n  resourceEncodedSize: 50000,\n  resourceDecodedSize: 50000,\n  resourceInitiatorType: 'img',\n  lcpValue: 3000,\n  url: 'https://example.com/page',\n  timestamp: 1234567890\n}\n```\n\n### Querying in New Relic\n\nYou can query the collected data in New Relic using NRQL:\n\n#### Main LCP Analysis\n```sql\nSELECT average(lcpValue), percentile(lcpValue, 75) \nFROM LCPPerformanceTrace \nWHERE lcpValue > 2500 \nSINCE 24 hours ago\n```\n\n#### Resource Analysis\n```sql\nSELECT resourceName, average(resourceDuration) \nFROM LCPResourceTrace \nWHERE resourceInitiatorType = 'img' \nFACET resourceName \nSINCE 24 hours ago\n```\n\n#### Join Events by Trace ID\n```sql\nSELECT lcp.lcpValue, res.resourceName, res.resourceDuration\nFROM LCPPerformanceTrace lcp \nJOIN LCPResourceTrace res ON lcp.traceId = res.traceId\nWHERE lcp.lcpValue > 3000\nSINCE 24 hours ago\n```\n\n## API Reference\n\n### `LCPPerformanceTracer`\n\n#### Constructor\n\n```typescript\nnew LCPPerformanceTracer(config?: LCPTracerConfig)\n```\n\nCreates a new instance of the LCP Performance Tracer.\n\n#### Methods\n\n##### `start(): void`\n\nStarts monitoring LCP and collecting performance data.\n\n##### `stop(): void`\n\nStops monitoring and cleans up resources.\n\n##### `isTracerRunning(): boolean`\n\nReturns whether the tracer is currently running.\n\n##### `getConfig(): Readonly<Required<LCPTracerConfig>>`\n\nReturns the current configuration.\n\n#### Static Methods\n\n##### `create(config?: LCPTracerConfig): LCPPerformanceTracer`\n\nFactory method to create a new tracer instance.\n\n##### `autoStart(config?: LCPTracerConfig): LCPPerformanceTracer`\n\nCreates and automatically starts a tracer when the DOM is ready.\n\n## Browser Support\n\n- Chrome 77+\n- Edge 79+\n- Safari 14.1+\n- Firefox 122+\n\nThe library includes fallback mechanisms for browsers that don't fully support the Performance Observer API.\n\n## Examples\n\n### Conditional Monitoring\n\n```javascript\n// Only monitor in production\nconst tracer = new LCPPerformanceTracer({\n  enabled: window.location.hostname === 'production.example.com',\n  lcpThreshold: 2500\n});\ntracer.start();\n```\n\n### Sampling Configuration\n\n```javascript\n// Sample 10% of sessions to reduce data volume\nconst tracer = new LCPPerformanceTracer({\n  samplingRate: 0.1,\n  lcpThreshold: 2500\n});\ntracer.start();\n```\n\n### Debug Mode\n\n```javascript\n// Enable detailed logging for troubleshooting\nconst tracer = new LCPPerformanceTracer({\n  debug: true,\n  lcpThreshold: 2500\n});\ntracer.start();\n```\n\n## Testing\n\n```bash\n# Run unit tests\nnpm test\n\n# Run tests with coverage\nnpm run test:coverage\n\n# Run tests in watch mode\nnpm run test:watch\n```\n\n## Building\n\n```bash\n# Build the library (all formats)\nnpm run build\n\n# Build standalone browser version only\nnpm run build:standalone\n\n# Watch mode for standalone development\nnpm run build:standalone:watch\n\n# Clean build artifacts\nnpm run clean\n\n# Run linting\nnpm run lint\n\n# Type checking\nnpm run typecheck\n```\n\n## Standalone Build\n\nThe standalone build creates UMD bundles that can be used directly in browsers:\n\n- `dist/standalone/lcp-performance-tracer.js` - Development version (with source maps)\n- `dist/standalone/lcp-performance-tracer.min.js` - Production version (minified, with source maps)\n\n### File Sizes\n\n- Development build: ~34KB\n- Production build (minified): ~15KB\n- Production build (minified + gzipped): ~5KB\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Support\n\nFor issues and questions, please use the [GitHub issues page](https://github.com/your-org/lcp-performance-tracer/issues).","readmeFilename":"README.md"}