elastic · smnschndr · Jul 23, 2026
@@ -0,0 +1,93 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.
@@ -0,0 +1,3 @@
+dependencies:
+  ecs:
+    reference: "git@v9.3.0"
@@ -0,0 +1,111 @@
+{{- generatedHeader }}
+# evcc Integration for Elastic
+
+## Overview
+
+The evcc integration collects site and per-loadpoint metrics, and application logs, from [evcc](https://evcc.io), the open-source solar charging and energy management system. It enables monitoring of solar production, home battery state, grid power flow, EV charging activity, and operational issues (vehicle API errors, device read failures, charger warnings) in Elastic.
+
+### Compatibility
+
+This integration collects data from the evcc REST API (`/api/state`) and, on Linux hosts where evcc runs as a systemd service, from its journald logs. It has been verified against evcc 0.312.x, but is expected to work with other recent evcc releases as well. Refer to the [evcc REST API documentation](https://docs.evcc.io/en/integrations/rest-api) for details. evcc's log line format is not formally documented upstream and may change between releases; unrecognized log lines are still shipped as plain `message` events rather than being dropped.
+
+### How it works
+
+This integration uses two collection methods:
+* The [CEL input](https://www.elastic.co/guide/en/beats/filebeat/current/filebeat-input-cel.html) periodically polls the evcc REST API. Two metrics data streams each poll `/api/state` independently: one extracts site-level metrics (solar, grid, battery, home power, cost statistics) and the other splits the `loadpoints` array into one event per configured charge point (charging state, power, energy, connected vehicle).
+* The [journald input](https://www.elastic.co/guide/en/beats/filebeat/current/filebeat-input-journald.html) reads evcc's application logs directly from the systemd journal and parses them into ECS fields.
+
+## What data does this integration collect?
+
+The evcc integration collects metrics and logs of the following types:
+* **Site**: home power, grid power, solar (PV) power and energy, home battery power/state of charge, and cost/CO2/solar-share statistics for several reporting periods.
+* **Loadpoint**: per-charge-point mode, charging/connected/enabled state, charge power, charged energy, session duration, effective current/SoC limits, and connected vehicle name/SoC/range.
+* **Log**: evcc's own application logs collected via journald. Charging session lifecycle events (car connected/disconnected, charging started/stopped), vehicle API errors (timeouts, HTTP error status codes), device read failures (battery/PV/grid meter connectivity), and charger logic warnings are parsed into dedicated ECS fields (`event.action`, `event.category`, `event.outcome`, `destination.ip`/`port`, `url.*`, `http.response.status_code`, etc.). High-volume DEBUG-level telemetry lines are kept as plain `message` text, since the same readings are already collected in structured form by the site and loadpoint data streams.
+
+### Supported use cases
+
+This integration enables dashboards and alerts for home energy management, such as tracking how much of your EV charging is solar-powered, monitoring home battery state of charge, being notified when a loadpoint stops charging unexpectedly, or alerting on repeated vehicle API or device read failures surfaced in the logs.
+
+## What do I need to use this integration?
+
+* A running evcc instance reachable over HTTP from the Elastic Agent, for the site and loadpoint metrics data streams. This integration does not currently support evcc instances that have password protection enabled.
+* For the log data stream, evcc must run as a systemd service (the default on Linux installations) so its output is captured by journald, and Elastic Agent must run on that same Linux host with access to the system journal.
+
+## How do I deploy this integration?
+
+### Agent-based deployment
+
+Elastic Agent must be installed. For more details, check the Elastic Agent [installation instructions](docs-content://reference/fleet/install-elastic-agents.md). You can install only one Elastic Agent per host.
+
+For the metrics data streams, Elastic Agent polls the evcc REST API directly over HTTP(S). For the log data stream, Elastic Agent must run on the same Linux host as evcc and reads its logs from the local systemd journal. Events are then processed via the integration's ingest pipelines.
+
+### Onboard / configure
+
+1. In Kibana, go to **Management > Integrations** and add the **evcc** integration.
+2. Set the **evcc URL** to the base URL of your evcc instance, e.g. `http://evcc.local:7070`.
+3. Optionally adjust the polling **Interval** for the site and loadpoint data streams (default: `30s`).
+4. To collect logs, deploy the log data stream's input to an Elastic Agent running directly on the host where evcc's systemd service runs. Adjust **Include Matches** if evcc runs under a different systemd unit name than `evcc.service`. Consider enabling **Drop debug-level logs** if you do not need evcc's high-volume DEBUG telemetry.
+5. Assign the integration to an Elastic Agent policy and deploy it to an agent with the required network/host access.
+
+### Validation
+
+After the integration is running, confirm data is arriving by checking the `metrics-evcc.site-*`, `metrics-evcc.loadpoint-*`, and `logs-evcc.log-*` data streams in **Discover**, or by browsing the field values in the installed dashboards.
+
+## Troubleshooting
+
+For help with Elastic ingest tools, check [Common problems](https://www.elastic.co/docs/troubleshoot/ingest/fleet/common-problems).
+
+If no metrics appear, verify that the evcc URL is reachable from the host running Elastic Agent (e.g. `curl <evcc URL>/api/state`) and that no reverse proxy authentication is blocking the request.
+
+If no logs appear, verify that evcc is running as a systemd service on the same host as the Elastic Agent collecting logs (`systemctl status evcc`), and that the **Include Matches** filter matches its actual unit name (check with `systemctl list-units | grep evcc`).
+
+## Scaling
+
+For more information on architectures that can be used for scaling this integration, check the [Ingest Architectures](https://www.elastic.co/docs/manage-data/ingest/ingest-reference-architectures) documentation.
+
+## Reference
+
+### site
+
+The `site` data stream provides site-level metrics from evcc of the following types: home power, grid power, solar power/energy, home battery power/SoC/capacity, and cost/CO2/solar-share statistics.
+
+#### site fields
+
+{{ fields "site" }}
+
+#### site sample event
+
+{{ event "site" }}
+
+### loadpoint
+
+The `loadpoint` data stream provides one event per evcc loadpoint (charge point) of the following types: mode, charging/connected/enabled state, charge power/energy/duration, effective current/SoC limits, and connected vehicle details.
+
+#### loadpoint fields
+
+{{ fields "loadpoint" }}
+
+#### loadpoint sample event
+
+{{ event "loadpoint" }}
+
+### log
+
+The `log` data stream provides evcc's own application logs, collected via journald, of the following types: charging session lifecycle events, vehicle API errors, device read failures, charger logic warnings, and DEBUG-level telemetry (kept as plain text).
+
+#### log fields
+
+{{ fields "log" }}
+
+#### log sample event
+
+{{ event "log" }}
+
+### Inputs used
+
+{{ inputDocs }}
+
+### API usage
+
+These APIs are used with this integration:
+* [`GET /api/state`](https://docs.evcc.io/en/integrations/rest-api) &mdash; returns the complete state of the evcc instance, including site, loadpoint, and vehicle data.
@@ -0,0 +1,5 @@
+FROM ubuntu:20.04
+
+RUN apt-get update \
+      && apt install -y systemd-journal-remote \
+      && rm -rf /var/lib/apt/lists/*
@@ -0,0 +1,23 @@
+version: '2.3'
+services:
+  evcc:
+    image: docker.elastic.co/observability/stream:v0.18.0
+    hostname: evcc
+    ports:
+      - 8080
+    volumes:
+      - ./files:/files:ro
+    environment:
+      PORT: '8080'
+    command:
+      - http-server
+      - --addr=:8080
+      - --config=/files/config.yml
+  journald:
+    build: .
+    volumes:
+      - ./sample_logs:/sample_logs:ro
+      - ${SERVICE_LOGS_DIR}:/var/log
+    # Use journalctl -o export > <name>.export to write logs to journald export format.
+    # This then creates a new binary journal file from those logs to use in testing.
+    command: /bin/sh -c "/lib/systemd/systemd-journal-remote -o /var/log/test.journal /sample_logs/*.export"
@@ -0,0 +1,106 @@
+rules:
+  - path: /api/state
+    methods: ['GET']
+    responses:
+      - status_code: 200
+        headers:
+          Content-Type:
+            - 'application/json'
+        body: |-
+          {{ minify_json `
+          {
+            "siteTitle": "My Home",
+            "version": "0.312.1",
+            "currency": "EUR",
+            "homePower": 500,
+            "grid": {
+              "name": "grid",
+              "power": -407.8566601636994
+            },
+            "pvPower": 8307.59154846352,
+            "pvEnergy": 24521300,
+            "battery": {
+              "power": 0,
+              "capacity": 13.4,
+              "soc": 76,
+              "devices": [
+                {
+                  "name": "battery",
+                  "power": 0,
+                  "capacity": 13.4,
+                  "soc": 76,
+                  "controllable": true
+                }
+              ]
+            },
+            "statistics": {
+              "30d": {
+                "avgCo2": 62.14859311838828,
+                "avgPrice": 0.11162431782896463,
+                "chargedKWh": 221.77069867393018,
+                "solarPercentage": 83.70583267207702
+              },
+              "365d": {
+                "avgCo2": 62.14859311838828,
+                "avgPrice": 0.11162431782896463,
+                "chargedKWh": 221.77069867393018,
+                "solarPercentage": 83.70583267207702
+              },
+              "thisYear": {
+                "avgCo2": 62.14859311838828,
+                "avgPrice": 0.11162431782896463,
+                "chargedKWh": 221.77069867393018,
+                "solarPercentage": 83.70583267207702
+              },
+              "total": {
+                "avgCo2": 62.14859311838828,
+                "avgPrice": 0.11162431782896463,
+                "chargedKWh": 221.77069867393018,
+                "solarPercentage": 83.70583267207702
+              }
+            },
+            "loadpoints": [
+              {
+                "title": "Garage",
+                "mode": "pv",
+                "charging": true,
+                "connected": true,
+                "enabled": true,
+                "connectedDuration": 3600,
+                "chargePower": 6900,
+                "chargedEnergy": 103212.794,
+                "chargeDuration": 91241,
+                "chargeRemainingDuration": 41739,
+                "chargeRemainingEnergy": 40000,
+                "effectiveLimitSoc": 95,
+                "effectiveMinCurrent": 3,
+                "effectiveMaxCurrent": 13,
+                "chargerStatusReason": "unknown",
+                "last24hEnergy": 88014,
+                "last7dEnergy": 190432,
+                "vehicleName": "blue e-Golf",
+                "vehicleSoc": 63,
+                "vehicleRange": 210
+              },
+              {
+                "title": "Carport",
+                "mode": "off",
+                "charging": false,
+                "connected": false,
+                "enabled": false,
+                "connectedDuration": 0,
+                "chargePower": 0,
+                "chargedEnergy": 0,
+                "chargeDuration": 0,
+                "chargeRemainingDuration": 0,
+                "chargeRemainingEnergy": 0,
+                "effectiveLimitSoc": 100,
+                "effectiveMinCurrent": 6,
+                "effectiveMaxCurrent": 16,
+                "chargerStatusReason": "unknown",
+                "last24hEnergy": 0,
+                "last7dEnergy": 0
+              }
+            ]
+          }
+          ` }}