> ## Documentation Index
> Fetch the complete documentation index at: https://docs.germainux.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Ingestion API

> GermainUX exposes a REST API that enables users to insert data into the Germain Datamart.

Availability
2022.1 or later

> **[Feature](#feature)**
>
> REST gateway to Datamart

> **[Usage](#usage)**
>
> Submit facts in batches

## Feature

GermainUX exposes a REST API that enables users to insert data into the Germain Datamart. The Ingestion API serves as a means to seamlessly integrate external data sources with GermainUX, allowing users to import data from various systems, applications, or sources directly into the Germain Datamart for analysis and monitoring. By leveraging the Ingestion API, users can programmatically push data into GermainUX, ensuring that the monitoring system stays up to date with the latest information from different data sources. This API facilitates the ingestion of data in a structured manner, ensuring data integrity and consistency within the Germain Datamart.

Whether it's user activity logs, application performance metrics, server logs, or any other relevant data, the Ingestion API provides a convenient and standardized method for importing this data into GermainUX, enabling comprehensive monitoring and analysis of the collected information.

By utilizing the Ingestion API, organizations can leverage the power of GermainUX to gain valuable insights, detect anomalies, optimize performance, and make data-driven decisions based on a holistic view of their systems and applications.

For detailed information on how to use the Ingestion API and integrate external data sources with GermainUX, please refer to the documentation or developer resources provided by the GermainUX platform.

## Usage

The primary REST interface of the ingestion API provides a way to submit a list of facts to GermainUX:

```text theme={null}
POST /ingestion/fact
[
    { fact },
    { fact },
    ...
]
```

A status code of 200 indicates that the request was received successfully. In case of an error, a specific error message will be returned by the service.

### Data Model Fields

Every fact submitted this way must conform to one of the [fact model types](https://docs.germainux.com/main/data-model.md) available in GermainUX. While each model will have a different set of properties, there are some that are shared across all models. The following example shows common properties shared across fact types:

```json theme={null}
[
    {
        "id": "b43bb20b234a93ba00ed16cb",
        "myClassName": "GenericEvent",
        "type": "Custom:Error",
        "timestamp": "2024-03-14T17:38:00Z",
   		"provenance": "S|2023.4|de7ae27c3e4e|ANALYTICS|6b4a1d76-51ef-4d2a-9f0c-67fae88469bd"
		"dataSource: "a92068c",
		"update: false,
		...
    },
    ...
]
```

| Field Name | Required? | Default Value | Description |
| - | - | - | - |
| id | no | yes | Unique identifier for this data point. Stores up to 12 bytes or 24 hexadecimal characters. If not provided, GermainUX will generate a unique ID automatically. |
| myClassName | yes | no | The name of the mode type of this fact. See [Data Model](https://docs.germainux.com/main/data-model.md) for a list of available types. |
| type | yes | no | A string value that matches the fact category of the KPI you want to store this data as. |
| timestamp | yes | no | A timestamp associated with this data point. Timestamp should be formatted as either a [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) compliant string, or a Unix epoch value with milliseconds. |
| provenance | no | yes | The provenance value identifies the source that generated this data point. GermainUX components use a hierarchical value that encodes the type, version, and ID of the source that generated the data. You are free to chose a custom value, but we recommend that you prefix it with “X\|” to identify it as such in that case. |
| dataSource | no | no | The ID of the [data source](https://docs.germainux.com/main/data-source.md) configured in GermainUX that this data was collected for. |
| update | no | yes | If set to true, will mark this fact as an update to a previous fact with the same ID. Defaults to false. |

### Examples

#### Error Event

The following example records a generic error including the affected user and error message.

```bash theme={null}
curl -X POST 'https://<your germain env URL>/ingestion/fact' \
--header 'Content-Type: application/json' \
--data '[{
    "myClassName": "GenericEvent",
    "type": "System:Error",
    "timestamp": "2024-01-22T14:21:23Z",
    "provenance": "X|integration",
    "name": "SYS-ERR-348",
    "system": {
      "hostname": "XDF1938"
    },
    "user": {
      "name": "admin"
    },
    "details": "Unable to process request. Remaining requests have been cancelled."
  }]'
```

#### SQL Statement Execution

The following example records the execution of a SQL query. Specifically, it records which database the query was executed by, the SQL text, and the query duration.

```sql theme={null}
curl -X POST 'https://<your germain env URL>/ingestion/fact' \
--header 'Content-Type: application/json' \
--data '[{
    "myClassName": "GenericTransaction",
    "type": "SQL:Query",
    "timestamp": "2024-01-22T14:21:23Z",
    "provenance": "X|integration",
    "name": "gqrwquv0utrb7",
    "system": {
      "hostname": "XDF1938"
    },
    "database": {
      "name": "SPROD-1",
      "flavor": "ORACLE"
    },
    "user": {
      "name": "perftest"
    },
    "duration": 0.562,
    "details": "select * from COMMON_TABS where QNAME = ? order by LAST_MOD"
  }]'
```

#### Mulesoft API Metric

The following example creates a data point in GermainUX each time a “SR Update” occurs in Mulesoft.

```text theme={null}
curl -X POST 'https://<your germain env URL>/ingestion/fact' \
--header 'Content-Type: application/json' \
--data '[{
        "myClassName": "GenericMetric",
        "type": "Mulesoft:APIMetric",
        "name": "SR Update",
        "timestamp": "2022-05-16T20:54:40Z",
        "value": 500,
        "database":{
            "name":"1234-1234554-134514-145",
            "flavor":"ORACLE"
        },
        "pid":"320",
        "application": {
            "component": "4.3.2",
            "name": "CSMulesoft-Cases-api"
        },
        "system": {
            "name": "CSSendSMS",
            "hostname": "Platform"
        }
    }]'
```

In GermainUX:

A datapoint gets inserted into GermainUX’s data warehouse, and it looks like this on a GermainUX's drillthrough dashboard:

![Data Ingestion API: Mulesoft API Metric](https://mintcdn.com/germain-ux/npHkPTFCfiH3hzwe/images/main/data-ingestion-api/Screenshot-2023-11-24-at-11.27.46.png?fit=max\&auto=format\&n=npHkPTFCfiH3hzwe\&q=85\&s=777275d5d8b738de58c6815d73cab69f)

### Authentication

No authentication is required to submit new facts. In order to secure the ingestion REST endpoints, we recommend setting up IP-range ACLs at the level of your load balancer or firewall. Please [contact our support team](https://docs.germainux.com/main/support.md) to help you configure this.

## Get Help

> **[Contact GermainUX Support](https://docs.germainux.com/main/support.md)**
>
> The Germain Team can help you set this up.

> **Can't find what you need?**
>
> Search all GermainUX docs with **Ctrl + K**, or use the feedback buttons at the bottom of this page to tell us what is missing.

The content of this document is proprietary to GERMAIN SOFTWARE.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.