{"id":46890837,"url":"https://github.com/twiebe/hassos-addons-vector","last_synced_at":"2026-04-22T20:00:35.521Z","repository":{"id":340734169,"uuid":"1164205279","full_name":"twiebe/hassos-addons-vector","owner":"twiebe","description":"Home Assistant Vector Addon / App for shipping logs","archived":false,"fork":false,"pushed_at":"2026-03-10T23:44:59.000Z","size":26,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-11T02:05:40.852Z","etag":null,"topics":["logging","loki","vector","victorialogs"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/twiebe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-22T19:44:41.000Z","updated_at":"2026-03-10T22:24:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/twiebe/hassos-addons-vector","commit_stats":null,"previous_names":["twiebe/hassos-addons-vector"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/twiebe/hassos-addons-vector","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twiebe%2Fhassos-addons-vector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twiebe%2Fhassos-addons-vector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twiebe%2Fhassos-addons-vector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twiebe%2Fhassos-addons-vector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/twiebe","download_url":"https://codeload.github.com/twiebe/hassos-addons-vector/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twiebe%2Fhassos-addons-vector/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32152607,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T17:06:48.269Z","status":"ssl_error","status_checked_at":"2026-04-22T17:06:19.037Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["logging","loki","vector","victorialogs"],"created_at":"2026-03-10T22:40:11.861Z","updated_at":"2026-04-22T20:00:35.489Z","avatar_url":"https://github.com/twiebe.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hassos-addons-vector\n\nSource repository for the **Vector** Home Assistant OS addon. The addon is distributed via [twiebe/hassos-addons](https://github.com/twiebe/hassos-addons).\n\n[Vector](https://vector.dev) is a high-performance observability data pipeline. This addon runs Vector as a Home Assistant OS service, collecting logs from the systemd journal and forwarding them to a configured sink.\n\n## How it works\n\nOn startup the addon generates a Vector configuration from your addon options and starts the Vector process. The generated configuration is printed to the addon log at startup (with credentials obfuscated) so you can verify it without needing shell access.\n\n## Sources\n\nLogs are collected from the **systemd journal** (`journald`), which on Home Assistant OS includes all system services, the supervisor, and any Docker containers running as addons.\n\n## Transforms\n\nTwo optional transforms can be applied before logs are forwarded:\n\n### Lowercase Field Names\n\nNormalises all field names to lowercase. Journald emits many fields in uppercase (e.g. `CONTAINER_NAME`, `_SYSTEMD_UNIT`). Enabling this makes field names consistent and easier to work with in most log backends.\n\n### Rename Host Field\n\nVector's journald source attaches the hostname under the field `host`. If your log backend or query conventions expect a different name (e.g. `hostname`), enable this transform and set the desired field name.\n\nThe two transforms are independent and can be combined. When both are enabled, lowercase is applied first, then the host field is renamed.\n\n## Sinks\n\n### VictoriaLogs\n\n[VictoriaLogs](https://docs.victoriametrics.com/victorialogs/) exposes an Elasticsearch-compatible bulk ingest API, which is what Vector uses under the hood — the sink type in Vector's config is `elasticsearch`, but the addon models this honestly as `victorialogs` since the configuration (in particular the `query` parameters) is specific to VictoriaLogs and not portable to plain Elasticsearch or OpenSearch.\n\nThe following VictoriaLogs-specific query parameters are always set in the generated config:\n\n| Parameter | Value | Purpose |\n|---|---|---|\n| `_msg_field` | `message` | Tells VictoriaLogs which field contains the log message |\n| `_time_field` | `timestamp` | Tells VictoriaLogs which field contains the timestamp |\n| `_stream_fields` | auto or configured | Fields used to group logs into streams |\n\n`_stream_fields` is auto-generated based on the active transforms: it uses the host field name (as renamed, if applicable) and `container_name` or `CONTAINER_NAME` depending on whether lowercase is enabled. You can override this by setting the Stream Fields option explicitly.\n\nCompression is fixed at `gzip` and the Elasticsearch healthcheck is disabled — VictoriaLogs does not expose that endpoint.\n\n| Option | Description |\n|---|---|\n| Endpoint URL | Full URL of your VictoriaLogs ingest endpoint |\n| Auth Username | Basic auth username (leave empty to disable) |\n| Auth Password | Basic auth password |\n| Stream Fields | Override the auto-generated `_stream_fields` value |\n| Ignore Fields | Comma-separated list of fields to drop before forwarding (e.g. `log.offset,event.original`) |\n\n### Loki\n\n[Loki](https://grafana.com/oss/loki/) is supported via Vector's native `loki` sink. This includes [Grafana Cloud](https://grafana.com/products/cloud/) hosted Loki.\n\nStream labels are auto-generated from the active transforms using the same logic as VictoriaLogs stream fields: the host field name and `container_name` / `CONTAINER_NAME` depending on whether lowercase is enabled. Fields used as labels are removed from the log body to avoid duplication. Compression is fixed at `gzip`.\n\n| Option | Description |\n|---|---|\n| Endpoint URL | Full URL of your Loki endpoint (e.g. `https://logs-prod-us-central1.grafana.net`) |\n| Auth Username | Basic auth username — for Grafana Cloud this is your numeric org ID |\n| Auth Password | Basic auth password — for Grafana Cloud this is your API token |\n| Tenant ID | Sets the `X-Scope-OrgID` header — required for Grafana Cloud and multi-tenant Loki deployments |\n| Encoding | Log body encoding: `text` (the `message` field only) or `json` (full structured event) |\n\n## Config override\n\nFor use cases not covered by the addon options, you can supply a handwritten Vector configuration file. Enable **Override Config** and set **Override Config Path** to the path of your file (default: `/config/vector.yaml`).\n\nThe override file lives in the addon's own config directory, which Home Assistant mounts from `/addon_configs/{repo}_vector/` on the host. You can manage files there via the Samba addon or the Studio Code Server addon.\n\nWhen override mode is active, **all other addon options are ignored entirely** — the addon copies your file directly to the Vector config location and starts Vector with it. The generated config is not written and no transforms are applied. The override file is still printed to the addon log at startup (with passwords obfuscated).\n\nThis is useful when you need additional inputs, complex routing, or full control over the Vector topology.\n\nThe override file must be a valid [Vector configuration file](https://vector.dev/docs/reference/configuration/).\n\n## Development\n\nDev builds are triggered automatically on every push to a non-`main` branch. Images are tagged with the sanitized branch name and pushed to GHCR.\n\nRelease builds are triggered when a GitHub release is published. Tag the release with a bare version number (e.g. `0.1.0`). After a successful build the workflow automatically opens a commit in `hassos-addons` bumping the version in `vector/config.yaml`. This requires a `HASSOS_ADDONS_PAT` secret set in this repo with write access to `hassos-addons`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwiebe%2Fhassos-addons-vector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftwiebe%2Fhassos-addons-vector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwiebe%2Fhassos-addons-vector/lists"}