[Yandex Cloud documentation](../index.md) > [Monium](index.md) > Getting started # Getting started with Monium Monium is a platform for collecting [metrics](metrics/overview.md), [logs](logs/quickstart.md), and [traces](traces/index.md) from Yandex Cloud, other clouds, or your local infrastructure. Follow this guide to send telemetry data from your app or demo app via [OTel Collector](https://opentelemetry.io/docs/) and view it in Monium. To get started with app telemetry: 1. [Get your cloud ready](#before-begin). 1. [Create a service account and API key](#create-ca-key). 1. [Set up your application ](#setup-app). 1. [View the data in Monium](#view-telemetry). ## Get your cloud ready {#before-begin} {% list tabs group=instructions %} - Management console {#console} 1. Log in to the [management console](https://console.yandex.cloud) or sign up. If not signed up yet, navigate to the management console and follow the instructions. 1. On the [**Yandex Cloud Billing** page](https://center.yandex.cloud/billing/accounts), make sure you have a linked [billing account](../billing/concepts/billing-account.md) with the `ACTIVE` or `TRIAL_ACTIVE` status. If you do not have a billing account yet, [create one](../billing/quickstart/index.md#create_billing_account). If you have an active billing account, you can navigate to the [cloud page](https://console.yandex.cloud/cloud) to create or select a [folder](../resource-manager/concepts/resources-hierarchy.md#folder) for your infrastructure. [Learn more about clouds and folders here](../resource-manager/concepts/resources-hierarchy.md). {% endlist %} ## Create a service account and API key {#create-ca-key} {% list tabs group=instructions %} - Management console {#console} 1. In the [management console](https://console.yandex.cloud), navigate to the folder where you want to store your telemetry. 1. Navigate to **Identity and Access Management**. 1. Click **Create service account**. 1. Enter a name for the service account, e.g., `monium-sa`. 1. Click ![image](../_assets/console-icons/plus.svg) **Add role** and add the `monium.telemetry.writer` [role](security/index.md#monium-telemetry-writer). If you plan to transfer only particular data types, instead of `monium.telemetry.writer`, select one or more roles with narrower sets of permissions: `monium.metrics.writer`, `monium.logs.writer`, `monium.traces.writer`. 1. Click **Create**. 1. In the list that opens, select the service account you created. 1. In the top panel, click ![image](../_assets/console-icons/plus.svg) **Create new key** and select **Create API key**. 1. Select **Scope** for `yc.monium.telemetry.write`. If you plan to transfer only particular data types, instead of `yc.monium.telemetry.write`, select one or more narrower [scopes](../iam/concepts/authorization/api-key.md#scoped-api-keys): `yc.monium.metrics.write`, `yc.monium.logs.write`, `yc.monium.traces.write`. 1. Optionally, set **Expires at** for the new API key. 1. Click **Create**. 1. Save the secret key you got for the next step. After you close the window, you will not be able to view the secret key again. {% endlist %} ## Set up your application {#setup-app} In Monium, telemetry has this hierarchy: project → cluster → service. Data for each service-cluster pair is distributed to individual shards. The method of configuring your application depends on whether telemetry is already configured or not. If you have already configured telemetry in the application, [specify the connection parameters for Monium](#monium-connect). If telemetry has not yet been configured, or if you do not have an application, [perform a complete setup](#otel-settings). ### Specify the Monium connection settings if telemetry is already configured in your app {#monium-connect} If you have an application and telemetry delivery is already configured, specify the parameters required to connect to Monium: * Authentication: [API key](#create-ca-key). * Endpoint: `ingest.monium.yandex.cloud:443`. * In the header: `x-monium-project=folder__` parameter. * In `OTEL_RESOURCE_ATTRIBUTES`: `cluster` or `deployment.name` and `service` or `service.name`. {% cut "Attribute priority when writing data" %} All metrics, logs, and traces in Monium have mandatory labels: `project`, `cluster`, and `service`. These labels form the shard key. When delivering telemetry in OpenTelemetry format, the values of these key attributes are assigned in the following order of priority: * Values assigned via HTTP or gRPC headers have the highest priority. * Then follow the values set in the resource attributes of the request body with the `cluster` and `service` keys. * Next are the values set in the resource attributes recommended by the OpenTelemetry semantic convention. * If the above-listed values are not set, the default value is used. The project name is only taken from the header. The algorithm for determining the shard key is presented in the table below. #| || header | resource’s own attribute | resource’s standard attribute | default value || || `x-monium-project` | — | — | — || || `x-monium-cluster` | `cluster` | `deployment.name` | `default` || || `x-monium-service` | `service` | `service.name`, `k8s.deployment.name`, `k8s.namespace.name` | `default` || |# {% endcut %} ### Set up transfer of telemetry from an app {#otel-settings} If you have your own application but telemetry delivery has not yet been configured in it, perform the necessary configuration. If you do not have a ready-made application for testing, use the demo app. {% list tabs group=instructions %} - Custom app {#own-app} 1. Set these environment variables: * `MONIUM_PROJECT`: Monium project name. By default, when you create a cloud and folder, two projects are created: `cloud__` and `folder__`. You can also [create other projects](collector/project.md#project-create). To test Monium, you can specify a project folder, e.g., `folder__b1g86q4m5vej********`. If entering it manually, make sure that `folder` is followed by two underscores. * `MONIUM_API_KEY`: API key. 1. Set up your application to send OTLP telemetry: * Install the [auto-instrumentation](https://opentelemetry.io/docs/concepts/instrumentation/#automatic-instrumentation) agent to automatically collect some telemetry data and send it to OTLP. * Add the [OpenTelemetry SDK](https://opentelemetry.io/docs/languages/) to your app. 1. [Install](https://opentelemetry.io/docs/collector/installation/) OTel Collector. You can send data to Monium directly from the OpenTelemetry SDK, without using the agent. 1. In the `otel-collector.yaml` [configuration](https://opentelemetry.io/docs/collector/configuration/) file, configure data transfer to Monium. Example of a minimal `otel-collector.yaml` configuration: ```yaml receivers: otlp: # Target type: OTLP protocols: # Protocols that OTel Collector listens to grpc: # gRPC, default port 4317 http: # HTTP, default port 4318 processors: cumulativetodelta: batch: exporters: # Connecting to Monium otlp/monium: compression: zstd endpoint: ingest.monium.yandex.cloud:443 headers: Authorization: "Api-Key ${env:MONIUM_API_KEY}" x-monium-project: "${env:MONIUM_PROJECT}" service: pipelines: metrics: # Transferring metrics receivers: [ otlp ] processors: [ batch, cumulativetodelta ] exporters: [ otlp/monium ] traces: # Transferring traces receivers: [ otlp ] processors: [ batch ] exporters: [ otlp/monium ] logs: # Transferring logs receivers: [ otlp ] processors: [ batch ] exporters: [ otlp/monium ] ``` 1. Set the environment variables to distribute data across shards in Monium: * `OTEL_SERVICE_NAME`: Name of your application or service. * `OTEL_RESOURCE_ATTRIBUTES="cluster=my-cluster"`: Name of the installation the application operates in, e.g., production or test environment. This is an optional setting. The default value is `cluster=default`. 1. Run your app and start sending telemetry. - Demo app {#demo-app} In this example, you will install the [Spring PetClinic](https://github.com/spring-projects/spring-petclinic) demo app and configure it to send telemetry to Monium. To install the demo application, you can temporarily create a Yandex Compute Cloud [VM](../compute/concepts/vm.md). Learn more about creating a suitable VM [here](../compute/operations/vm-create/create-linux-vm.md). Below are examples of commands for installing the demo application on Linux Ubuntu. {% note warning %} For the `OTel Collector` agent to work correctly, the VM or server must allow _outgoing traffic_ on TCP port `443`. For the demo application to work correctly, the VM or server must allow _incoming traffic_ on TCP ports `4317`, `4318`, and `8080`. If you are using a Compute Cloud VM, [create](../vpc/operations/security-group-create.md) and [link](../compute/operations/vm-control/vm-change-security-groups-set.md) to it a [security group](../vpc/concepts/security-groups.md) allowing these traffic types. {% endnote %} 1. Install [Git](https://git-scm.com/install/) and [Java](https://jdk.java.net/) suitable for your OS. For example: ```bash sudo apt update sudo apt install -y git openjdk-17-jdk ``` 1. Download and install an [OTel Collector](https://github.com/open-telemetry/opentelemetry-collector-releases/releases) agent suitable for your OS. For example: ```bash wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.144.0/otelcol_0.144.0_linux_amd64.tar.gz tar xvf otelcol_0.144.0_linux_amd64.tar.gz ``` 1. Set environment variables containing data for agent authentication in Monium: ```bash export MONIUM_PROJECT=folder__ export MONIUM_API_KEY= ``` Where: * ``: [ID of the folder](../resource-manager/operations/folder/get-id.md) to house your Monium [project](concepts/glossary.md#project). * ``: Service account [API key](../iam/concepts/authorization/api-key.md). This [service account](../iam/concepts/users/service-accounts.md) must have the `monium.telemetry.writer` [role](security/index.md#monium-telemetry-writer) or more granular roles to writing metrics, logs, or traces. The API key must have the `yc.monium.telemetry.write` [scope](../iam/concepts/authorization/api-key.md#scoped-api-keys) or narrower scopes for writing metrics, logs, or traces. 1. Create a file named `otel-collector.yaml` and paste the following contents to it: ```yaml receivers: otlp: protocols: grpc: http: exporters: otlp_grpc/monium: compression: zstd endpoint: ingest.monium.yandex.cloud:443 headers: Authorization: "Api-Key ${env:MONIUM_API_KEY}" x-monium-project: "${env:MONIUM_PROJECT}" sending_queue: batch: service: pipelines: metrics: receivers: [ otlp ] exporters: [ otlp_grpc/monium ] traces: receivers: [ otlp ] exporters: [ otlp_grpc/monium ] logs: receivers: [ otlp ] exporters: [ otlp_grpc/monium ] telemetry: metrics: level: normal readers: - periodic: exporter: otlp: protocol: http/protobuf endpoint: http://localhost:4318 interval: 30000 timeout: 5000 ``` 1. Run the [OTel Collector](collector/opentelemetry.md) agent: ```bash ./otelcol --config otel-collector.yaml ``` Once active, the agent will start listening on ports `4317` (gRPC) and `4318` (HTTP). 1. Open a new terminal window, then download and build the `Spring PetClinic` application: ```bash git clone https://github.com/spring-projects/spring-petclinic cd spring-petclinic ./mvnw -DskipTests package ``` Result: ```text ... [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 53.308 s [INFO] Finished at: 2026-05-05T18:56:22Z [INFO] ------------------------------------------------------------------------ ``` 1. Download the OpenTelemetry Java agent: ```bash curl -L -o opentelemetry-javaagent.jar \ https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar ``` 1. Run the demo application using the Java agent to send telemetry to OTel Collector: ```bash cd ~/spring-petclinic OTEL_SERVICE_NAME=spring-petclinic \ OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE="delta" \ java -javaagent:./opentelemetry-javaagent.jar -jar target/*.jar ``` Result: ```text ... 2026-05-05T19:00:31.981Z INFO 3657 --- [ main] o.s.s.petclinic.PetClinicApplication : Started PetClinicApplication in 9.287 seconds (process running for 12.883) ``` 1. Open the running `Spring PetClinic` demo app in your browser: * If the application is installed on your local computer, its address is `http://localhost:8080`. * If you used a VM to install the application, its address is `http://:8080`. 1. Interact with the demo application UI as a user: open a menu, click a button, enter new owner details, schedule an appointment, etc. {% endlist %} After you finish your app setup, [view the telemetry in Monium](#view-telemetry). ## View the data in Monium {#view-telemetry} {% list tabs group=instructions %} - Monium UI {#console} 1. On the [Monium](https://monium.yandex.cloud) home page, select a data type section on the left: {% list tabs group=monium_telemetry_type %} - Metrics {#metrics} 1. At the top, set the data search time period on the timeline. 1. In the search bar, enter a query to search for telemetry data: * `project = `: Select the project specified in `x-monium-project` of the application's telemetry transmission configuration. This may be a cloud (`cloud__`) or folder (`folder__`) project, or another [project](collector/project.md#project-create). * `cluster = `: Select the name of the installation that runs your application. If no cluster is specified, `cluster = default` is used. * `service = `: Name of your application or service. You can use the `OTEL_SERVICE_NAME` environment variable to provide it. If you do not see the required labels in the suggestions, you can enter them manually. However, the system most likely has not received data with these labels. See [Data delivery troubleshooting](collector/troubleshooting.md) for possible solutions. 1. Click **Execute query** or **Execute**. The page will show data that matches the query. ![image](../_assets/monium/petclinic-metrics.png) More on [metrics](metrics/metric-explorer.md). - Logs {#logs} 1. At the top, set the data search time period on the timeline. 1. In the search bar, enter a query to search for telemetry data: * `project = `: Select the project specified in `x-monium-project` of the application's telemetry transmission configuration. This may be a cloud (`cloud__`) or folder (`folder__`) project, or another [project](collector/project.md#project-create). * `cluster = `: Select the name of the installation that runs your application. If no cluster is specified, `cluster = default` is used. * `service = `: Name of your application or service. You can use the `OTEL_SERVICE_NAME` environment variable to provide it. If you do not see the required labels in the suggestions, you can enter them manually. However, the system most likely has not received data with these labels. See [Data delivery troubleshooting](collector/troubleshooting.md) for possible solutions. 1. Click **Execute query** or **Execute**. The page will show data that matches the query. ![image](../_assets/monium/petclinic-logs.png) More on [logs](logs/logs-explorer.md). - Traces {#traces} 1. At the top, set the data search time period on the timeline. 1. In the search bar, enter a query to search for telemetry data: * `project = `: Select the project specified in `x-monium-project` of the application's telemetry transmission configuration. This may be a cloud (`cloud__`) or folder (`folder__`) project, or another [project](collector/project.md#project-create). * `cluster = `: Select the name of the installation that runs your application. If no cluster is specified, `cluster = default` is used. * `service = `: Name of your application or service. You can use the `OTEL_SERVICE_NAME` environment variable to provide it. If you do not see the required labels in the suggestions, you can enter them manually. However, the system most likely has not received data with these labels. See [Data delivery troubleshooting](collector/troubleshooting.md) for possible solutions. 1. Click **Execute query** or **Execute**. The page will show data that matches the query. ![image](../_assets/monium/petclinic-traces.png) More on [traces](traces/operations/traces-explorer.md). {% endlist %} 1. To view information about the data shard, select **Shards** on the left and then, the shard with your service name. {% endlist %} {% note info %} Keep in mind that data in Monium appears with a lag rather than immediately, since the Otel Collector starts sending data after 60 seconds. {% endnote %} To use the data you collected, you can create [dashboards](operations/dashboard/create.md) and [alerts](operations/alert/create-alert.md). #### See also {#see-also} * [Getting started with metrics](metrics/quickstart.md) * [Getting started with logs](logs/quickstart.md) * [Getting started with traces](traces/index.md) * [Creating a dashboard](operations/dashboard/create.md) * [Creating an alert](operations/alert/create-alert.md) * [Telemetry delivery methods](collector/index.md)