Skip to content

update readme #524

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Oct 1, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 27 additions & 66 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/parseablehq/.github/main/images/logo-dark.png">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/parseablehq/.github/main/images/logo.svg">
<img alt="Parseable Logo" src="https://raw.githubusercontent.com/parseablehq/.github/main/images/logo.svg">
<a href="https://www.parseable.io" target="_blank"><img src="https://raw.githubusercontent.com/parseablehq/.github/main/images/logo.svg" alt="Parseable" width="600" height="150" /></a>
</picture>
<br>
Cloud native log analytics
Expand All @@ -15,112 +15,73 @@
[![Docs](https://img.shields.io/badge/stable%20docs-parseable.io%2Fdocs-brightgreen?style=flat&color=%2373DC8C&label=Docs)](https://www.parseable.io/docs)
[![Build](https://img.shields.io/github/checks-status/parseablehq/parseable/main?style=flat&color=%2373DC8C&label=Checks)](https://github.com/parseablehq/parseable/actions)

</div>

Parseable is a lightweight, cloud native log observability and analytics engine. It is written in Rust and uses Apache Arrow and Parquet.
[Key Concepts](https://www.parseable.io/docs/concepts) | [Features](https://github.com/parseablehq/parseable#rocket-highlights) | [Documentation](https://www.parseable.io/docs/) | [Demo](https://demo.parseable.io/login?q=eyJ1c2VybmFtZSI6ImFkbWluIiwicGFzc3dvcmQiOiJhZG1pbiJ9) | [Integrations](https://www.parseable.io/docs/category/integrations) | [FAQ](https://www.parseable.io/docs/faq)

Parseable uses a simple, index-free mechanism to organize and query data allowing low latency, and high throughput ingestion and query. It can use either a local mount point or object storage (S3/compatible stores) for data storage.
</div>

For comparison, Parseable consumes up to **_~80% lower memory_** and **_~50% lower CPU_** than Elastic for similar ingestion throughput. Read more in the [benchmarks directory](./benchmarks/).
Parseable is a log analytics platform, built for the modern, cloud native era. Parseable uses a index-free mechanism to organize and query data allowing low latency, and high throughput ingestion and query.

- [Parseable UI Demo (Credentials: admin,admin) ↗︎](https://demo.parseable.io)
- [Grafana Dashboard Demo ↗︎](http://demo.parseable.io:3000/dashboards)
To get started, download the Parseable binary from [releases page ↗︎](https://github.com/parseablehq/parseable/releases/latest) and run it on your machine.

## :rocket: Features
For comparison, Parseable consumes up to **_~80% lower memory_** and **_~50% lower CPU_** than Elastic for similar ingestion throughput. Read more in the [benchmarks directory ↗︎](./benchmarks/).

- Choose your own storage backend - local drive or S3 (or compatible) object store.
- Ingestion API compatible with HTTP + JSON output of log agents.
- Query log data with PostgreSQL compatible SQL.
- [Grafana ↗︎](https://github.com/parseablehq/parseable-datasource) for visualization.
- [Send alerts ↗︎](https://www.parseable.io/docs/api/alerts) to webhook targets including Slack.
- [Stats API ↗︎](https://www.postman.com/parseable/workspace/parseable/request/22353706-b32abe55-f0c4-4ed2-9add-110d265888c3) to track ingestion and compressed data.
- Single binary includes all components - ingestion, store and query. Built-in UI.
For :stethoscope: commercial support and consultation, please reach out to us at [`[email protected]` ↗︎](mailto:[email protected]).

## :white_check_mark: Getting Started
## :zap: Quickstart

Run the below command to deploy Parseable in local storage mode with Docker.
Deploy Parseable in local storage mode with Docker.

```sh
mkdir -p $HOME/parseable/data
mkdir -p $HOME/parseable/staging

docker run -p 8000:8000 \
-v $HOME/parseable/data:/parseable/data \
-v $HOME/parseable/staging:/parseable/staging \
-e P_FS_DIR=/parseable/data \
-e P_STAGING_DIR=/parseable/staging \
parseable/parseable:latest \
parseable local-store
```

Once this runs successfully, you'll see dashboard at [http://localhost:8000](http://localhost:8000). You can login to the dashboard default credentials `admin`, `admin`.
Once this runs successfully, you'll see dashboard at [http://localhost:8000 ↗︎](http://localhost:8000). You can login to the dashboard default credentials `admin`, `admin`.

### Send log events
To ingest data, run the below command. This will send logs to the `demo` stream. You can see the logs in the dashboard.

```sh
curl --location --request POST 'http://localhost:8000/api/v1/ingest' \
--header 'X-P-META-meta1: value1' \
--header 'X-P-TAG-tag1: value1' \
--header 'X-P-Stream: demo' \
--header 'Authorization: Basic YWRtaW46YWRtaW4=' \
--header 'Content-Type: application/json' \
--data-raw '[
{
"id": "434a5f5e-2f5f-11ed-a261-0242ac120002",
"datetime": "24/Jun/2022:14:12:15 +0000",
"host": "153.10.110.81",
"user-identifier": "Mozilla/5.0 Gecko/20100101 Firefox/64.0",
"method": "PUT",
"status": 500,
"referrer": "http://www.google.com/"
"host": "153.10.110.81"
}
]'
```

Note: The `X-P-Stream` header is used to specify the log stream where data is sent. Parseable will create the stream automatically if it doesn't exist already.

### Query the stream

You can see the events in Parseable UI, or use the below curl command to see the query response on CLI.

NOTE: Please change the `startTime` and `endTime` to the time range corresponding to the event you sent in the previous step.

```sh
curl --location --request POST 'http://localhost:8000/api/v1/query' \
--header 'Authorization: Basic YWRtaW46YWRtaW4=' \
--header 'Content-Type: application/json' \
--data-raw '{
"query":"select * from demo",
"startTime":"2023-06-09T00:00:00+00:00",
"endTime":"2023-06-09T23:59:00+00:00"
}'
```

## :chart_with_upwards_trend: Benchmarking
## :rocket: Highlights

Parseable is benchmarked with [K6](https://k6.io). Please find the results and details on how to run the benchmark in your environment in the [benchmarks directory](./benchmarks/).
- Choose storage backend - local drive or S3 (or compatible) object store.
- Ingestion API compatible with HTTP + JSON output of log agents.
- Query log data with PostgreSQL compatible SQL.
- Single binary includes all components - ingestion, store and query. Built-in UI.

## :books: Documentation
### Enterprise ready

- [Complete documentation ↗︎](https://www.parseable.io/docs/)
- [Roadmap ↗︎](https://github.com/orgs/parseablehq/projects/4)
- [FAQ ↗︎](https://www.parseable.io/docs/faq)
- [Alerts ↗︎](https://www.parseable.io/docs/alerts)
- [RBAC ↗︎](https://www.parseable.io/docs/rbac)
- [OAuth2 ↗︎](https://www.parseable.io/docs/oidc)
- [Grafana ↗︎](https://github.com/parseablehq/parseable-datasource)
- [LLM ↗︎](https://www.parseable.io/docs/llm)
- [Stats ↗︎](https://www.postman.com/parseable/workspace/parseable/request/22353706-b32abe55-f0c4-4ed2-9add-110d265888c3)

## :dart: Motivation

Traditionally, logging has been seen as a text search problem. Log volumes were not high, and data ingestion or storage were not really issues. This led us to today, where all the logging platforms are primarily text search engines.

But with log data growing exponentially, today's log data challenges involve whole lot more – Data ingestion, storage, and observation, all at scale. We are building Parseable to address these challenges.

## :stethoscope: Support

- For bugs, please create issue on [GitHub ↗︎](https://github.com/parseablehq/parseable/issues).
- For commercial support and consultation, please reach out to us at [`[email protected]` ↗︎](mailto:[email protected]).
- Please consider supporting us on [GitHub Sponsors ↗︎](https://github.com/sponsors/parseablehq).

## :trophy: Contributing

Refer to the contributing guide [here ↗︎](https://www.parseable.io/docs/contributing).
[Contribution guide ↗︎](https://www.parseable.io/docs/contributing).

![Alt](https://repobeats.axiom.co/api/embed/7c4e0f51cd3b8f78d1da682c396a3b5bd855a6ba.svg "Repobeats analytics image")

### Contributors

Expand Down