{"id":14971831,"url":"https://github.com/grafana/pyroscope-lambda-extension","last_synced_at":"2026-03-11T04:31:29.672Z","repository":{"id":37591293,"uuid":"488454310","full_name":"grafana/pyroscope-lambda-extension","owner":"grafana","description":"Pyroscope AWS Lambda Extension","archived":false,"fork":false,"pushed_at":"2026-03-05T20:12:13.000Z","size":117,"stargazers_count":8,"open_issues_count":16,"forks_count":4,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-03-05T23:26:24.337Z","etag":null,"topics":["aws-lambda","go","profiling","pyroscope"],"latest_commit_sha":null,"homepage":"https://grafana.com/docs/pyroscope/latest/configure-client/aws-lambda","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grafana.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-05-04T04:43:09.000Z","updated_at":"2025-10-27T14:05:04.000Z","dependencies_parsed_at":"2024-06-19T22:51:59.231Z","dependency_job_id":"818a252f-4437-45e7-b634-30c15d999fab","html_url":"https://github.com/grafana/pyroscope-lambda-extension","commit_stats":{"total_commits":38,"total_committers":8,"mean_commits":4.75,"dds":0.7105263157894737,"last_synced_commit":"aad486164c7c06036307d4fdcb732d47016cf1a2"},"previous_names":["pyroscope-io/pyroscope-lambda-extension"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/grafana/pyroscope-lambda-extension","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fpyroscope-lambda-extension","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fpyroscope-lambda-extension/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fpyroscope-lambda-extension/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fpyroscope-lambda-extension/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grafana","download_url":"https://codeload.github.com/grafana/pyroscope-lambda-extension/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fpyroscope-lambda-extension/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30370797,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T21:41:54.280Z","status":"online","status_checked_at":"2026-03-11T02:00:07.027Z","response_time":84,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["aws-lambda","go","profiling","pyroscope"],"created_at":"2024-09-24T13:45:54.027Z","updated_at":"2026-03-11T04:31:29.643Z","avatar_url":"https://github.com/grafana.png","language":"Go","readme":"# pyroscope-lambda-extension\n\n# Usage\nAdd `pyroscope-lambda-extension` to your lambda\nIn your lambda, add the pyroscope client. For example, the go one\n\n```go\nfunc main() {\n\tpyroscope.Start(pyroscope.Config{\n\t\tApplicationName: \"simple.golang.lambda\",\n\t\tServerAddress:   \"http://localhost:4040\",\n\t})\n\n\tlambda.Start(HandleRequest)\n}\n```\nKeep in mind it needs to be setup BEFORE the handler setup.\nAlso the `ServerAddress` **MUST** be `http://localhost:4040`, which is the address of the relay server.\n\nThen set up the `PYROSCOPE_REMOTE_ADDRESS` environment variable.\nIf needed, the `PYROSCOPE_AUTH_TOKEN` can be supplied.\n\nFor a complete list of variables check the section below.\n\n## Configuration\n| env var                         | default                          | description                                                                                  |\n|---------------------------------|----------------------------------|----------------------------------------------------------------------------------------------|\n| `PYROSCOPE_REMOTE_ADDRESS`      | `https://ingest.pyroscope.cloud` | the pyroscope instance data will be relayed to                                               |\n| `PYROSCOPE_AUTH_TOKEN`          | `\"\"`                             | authorization key (token authentication)                                                     |\n| `PYROSCOPE_SELF_PROFILING`      | `false`                          | whether to profile the extension itself or not                                               |\n| `PYROSCOPE_LOG_LEVEL`           | `info`                           | `error` or `info` or `debug` or `trace`                                                      |\n| `PYROSCOPE_TIMEOUT`             | `10s`                            | http client timeout ([go duration format](https://pkg.go.dev/time#Duration))                 |\n| `PYROSCOPE_NUM_WORKERS`         | `5`                              | num of relay workers, pick based on the number of profile types                              |\n| `PYROSCOPE_FLUSH_ON_INVOKE`     | `false`                          | wait for all relay requests to be finished/flushed before next `Invocation` event is allowed |\n| `PYROSCOPE_HTTP_HEADERS`        | `{}`                             | extra http headers in json format, for example: {\"X-Header\": \"Value\"}                        |\n| `PYROSCOPE_TENANT_ID`           | `\"\"`                             | phlare tenant ID, passed as X-Scope-OrgID http header                                      |\n| `PYROSCOPE_BASIC_AUTH_USER`     | `\"\"` | HTTP basic auth user |\n| `PYROSCOPE_BASIC_AUTH_PASSWORD` | `\"\"`  | HTTP basic auth password  |\n| `PYROSCOPE_LOG_FORMAT`                  | `\"text\"`         | format to choose from from `\"text\"` and `\"json\"`                                        |\n| `PYROSCOPE_LOG_TIMESTAMP_FORMAT`        | `time.RFC3339`   | logging timestamp format ([go time format](https://golang.org/pkg/time/#pkg-constants)) |\n| `PYROSCOPE_LOG_TIMESTAMP_DISABLE`       | `false`          | disables automatic timestamps in logging output                                         |\n| `PYROSCOPE_LOG_TIMESTAMP_FIELD_NAME`    | `\"time\"`         | change default field name in logs of automatic timestamps                               |\n| `PYROSCOPE_LOG_LEVEL_FIELD_NAME`        | `\"level\"`        | change default field name in logs of level                                              |\n| `PYROSCOPE_LOG_MSG_FIELD_NAME`          | `\"msg\"`          | change default field name in logs of message                                            |\n| `PYROSCOPE_LOG_LOGRUS_ERROR_FIELD_NAME` | `\"logrus_error\"` | change default field name in logs of logrus error                                       |\n| `PYROSCOPE_LOG_FUNC_FIELD_NAME`         | `\"func\"`         | change default field name in logs of caller function                                    |\n| `PYROSCOPE_LOG_FILE_FIELD_NAME`         | `\"file\"`         | change default field name in logs of caller file                                        |\n\n# How it works\nThe profiler will run as normal, and periodically will send data to the relay server (the server running at `http://localhost:4040`).\nWhich will then relay that request to the Remote Address (configured as `PYROSCOPE_REMOTE_ADDRESS`)\n\nThe advantage here is that the lambda handler can run pretty fast, since it only has to send data to a server running locally.\n\nKeep in mind you are still billed by the whole execution (lambda handler + extension).\n\n\n# Developing\n## Initial setup\n1. a) Install [asdf](https://asdf-vm.com/guide/getting-started.html) then run `asdf install`\n1. b) Or if you prefer, install the appropriate go version (for the exact go version check `.tool-versions`)\n2. `make install-dev-tools`\n3. If you have installed using `asdf`, you need to reshim (`asdf reshim`), to make asdf aware of the global tools (eg `staticcheck`)\n\n\n\n## Running the extension\nYou can run the extension in dev mode. It will not register the extension.\n\nIt's useful to test the relay server initialization.\nKeep in mind there's no lambda execution, therefore to test data is being relayed correctly you need\nto ingest manually (hitting `http://localhost:4040/ingest`).\n\n`PYROSCOPE_DEV_MODE=true go run main.go`\n\n## Building the layer\nAlthough [it's technically possible](https://github.com/aws/aws-sam-cli/issues/1187#issuecomment-540029710), at the time of this writing I could not run a lambda extension build locally.\n\nTherefore to test it with a lambda locally you need to:\n\n1. Login to aws\n2. `make publish-layer-dev`\n\nIt will build and push the layer.\n\nIf you are testing using the hello-world app, don't forget to update the version in `Layers` field of template (./hello-world/template.yml)\n\n## Running the lambda locally\n`make lambda-local`\n\n## Other tips\nTo test pushing data to a local pyroscope instance, you can set up in the lambda layer\nthe ip address of your computer (eg http://192.168.1.30:4040)\n\n\n# Self hosting the extension\nIt's possible to publish the extension on your own AWS account\n\n```shell\nARCH=\"YOUR_ARCHITECTURE\"\nREGION=\"YOUR_REGION\"\n\nGOOS=linux GOARCH=$ARCH go build -o bin/extensions/pyroscope-lambda-extension main.go\ncd bin\nzip -r extension.zip extensions\naws lambda publish-layer-version \\\n  --layer-name \"pyroscope-lambda-extension\" \\\n  --region=$YOUR_REGION \\\n  --zip-file \"fileb://extension.zip\"\n```\n\n# Releasing\n\nReleases are managed by [`release-please`](https://github.com/googleapis/release-please). It assumes you are using [Conventional Commit messages].\n\nThe most important prefixes you should have in mind are:\n\n * `fix:` which represents bug fixes, and correlates to a SemVer patch.\n * `feat:` which represents a new feature, and correlates to a SemVer minor.\n * `feat!:`, or `fix!:`, `refactor!:`, etc., which represent a breaking change (indicated by the !) and will result in a SemVer major.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrafana%2Fpyroscope-lambda-extension","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrafana%2Fpyroscope-lambda-extension","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrafana%2Fpyroscope-lambda-extension/lists"}