├── .github └── ISSUE_TEMPLATE │ ├── bug-report-for-vnext-emulator.md │ ├── bug_report.md │ └── feature_request.md ├── .gitignore ├── Dockerfile ├── LICENSE ├── README.md ├── SECURITY.md ├── docs └── opentelemetry.md ├── mk.cmd ├── package_scripts ├── exportcert.ps1 ├── getaddr.ps1 ├── importcert.ps1 └── startemu.cmd └── run.cmd /.github/ISSUE_TEMPLATE/bug-report-for-vnext-emulator.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Bug report for vNext Emulator 3 | about: Create a report to help us improve 4 | title: '' 5 | labels: cosmosEmulatorVnextPreview, needs-triage 6 | assignees: xgerman 7 | 8 | --- 9 | 10 | **Describe the bug** 11 | A clear and concise description of what the bug is. 12 | 13 | **To Reproduce** 14 | Steps to reproduce the behavior: 15 | 1. Go to '...' 16 | 2. Click on '....' 17 | 3. Scroll down to '....' 18 | 4. See error 19 | 20 | **Expected behavior** 21 | A clear and concise description of what you expected to happen. 22 | 23 | **Screenshots** 24 | If applicable, add screenshots to help explain your problem. 25 | 26 | **Desktop (please complete the following information):** 27 | - OS: [e.g. iOS] 28 | - Browser [e.g. chrome, safari] 29 | - Version [e.g. 22] 30 | - SDK version 31 | - SDK language 32 | 33 | **Additional context** 34 | Add any other context about the problem here. 35 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/bug_report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Bug report 3 | about: Create a report to help us improve 4 | title: '' 5 | labels: '' 6 | assignees: sajeetharan 7 | 8 | --- 9 | 10 | **Describe the bug** 11 | A clear and concise description of what the bug is. 12 | 13 | **To Reproduce** 14 | Steps to reproduce the behavior: 15 | 1. Go to '...' 16 | 2. Click on '....' 17 | 3. Scroll down to '....' 18 | 4. See error 19 | 20 | **Expected behavior** 21 | A clear and concise description of what you expected to happen. 22 | 23 | **Screenshots** 24 | If applicable, add screenshots to help explain your problem. 25 | 26 | **Desktop (please complete the following information):** 27 | - OS: [e.g. iOS] 28 | - Browser [e.g. chrome, safari] 29 | - Version [e.g. 22] 30 | 31 | **Docker Images Used: ** 32 | - Windows 33 | - Linux 34 | 35 | **Arguments && Environment variables to start Docker: 36 | 37 | **Docker Environment** 38 | - Docker compose 39 | - Standalone 40 | - Others (Please specify) 41 |   42 | **Additional context** 43 | Add any other context about the problem here. 44 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature_request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Feature request 3 | about: Suggest an idea for this project 4 | title: '' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Is your feature request related to a problem? Please describe.** 11 | A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] 12 | 13 | **Describe the solution you'd like** 14 | A clear and concise description of what you want to happen. 15 | 16 | **Describe alternatives you've considered** 17 | A clear and concise description of any alternative solutions or features you've considered. 18 | 19 | **Additional context** 20 | Add any other context or screenshots about the feature request here. 21 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | ## Ignore Visual Studio temporary files, build results, and 2 | ## files generated by popular Visual Studio add-ons. 3 | 4 | # User-specific files 5 | *.suo 6 | *.user 7 | *.userosscache 8 | *.sln.docstates 9 | 10 | # User-specific files (MonoDevelop/Xamarin Studio) 11 | *.userprefs 12 | 13 | # Build results 14 | [Dd]ebug/ 15 | [Dd]ebugPublic/ 16 | [Rr]elease/ 17 | [Rr]eleases/ 18 | x64/ 19 | x86/ 20 | bld/ 21 | [Bb]in/ 22 | [Oo]bj/ 23 | [Ll]og/ 24 | 25 | # Visual Studio 2015 cache/options directory 26 | .vs/ 27 | # Uncomment if you have tasks that create the project's static files in wwwroot 28 | #wwwroot/ 29 | 30 | # MSTest test Results 31 | [Tt]est[Rr]esult*/ 32 | [Bb]uild[Ll]og.* 33 | 34 | # NUNIT 35 | *.VisualState.xml 36 | TestResult.xml 37 | 38 | # Build Results of an ATL Project 39 | [Dd]ebugPS/ 40 | [Rr]eleasePS/ 41 | dlldata.c 42 | 43 | # DNX 44 | project.lock.json 45 | artifacts/ 46 | 47 | *_i.c 48 | *_p.c 49 | *_i.h 50 | *.ilk 51 | *.meta 52 | *.obj 53 | *.pch 54 | *.pdb 55 | *.pgc 56 | *.pgd 57 | *.rsp 58 | *.sbr 59 | *.tlb 60 | *.tli 61 | *.tlh 62 | *.tmp 63 | *.tmp_proj 64 | *.log 65 | *.vspscc 66 | *.vssscc 67 | .builds 68 | *.pidb 69 | *.svclog 70 | *.scc 71 | 72 | # Chutzpah Test files 73 | _Chutzpah* 74 | 75 | # Visual C++ cache files 76 | ipch/ 77 | *.aps 78 | *.ncb 79 | *.opendb 80 | *.opensdf 81 | *.sdf 82 | *.cachefile 83 | *.VC.db 84 | *.VC.VC.opendb 85 | 86 | # Visual Studio profiler 87 | *.psess 88 | *.vsp 89 | *.vspx 90 | *.sap 91 | 92 | # TFS 2012 Local Workspace 93 | $tf/ 94 | 95 | # Guidance Automation Toolkit 96 | *.gpState 97 | 98 | # ReSharper is a .NET coding add-in 99 | _ReSharper*/ 100 | *.[Rr]e[Ss]harper 101 | *.DotSettings.user 102 | 103 | # JustCode is a .NET coding add-in 104 | .JustCode 105 | 106 | # TeamCity is a build add-in 107 | _TeamCity* 108 | 109 | # DotCover is a Code Coverage Tool 110 | *.dotCover 111 | 112 | # NCrunch 113 | _NCrunch_* 114 | .*crunch*.local.xml 115 | nCrunchTemp_* 116 | 117 | # MightyMoose 118 | *.mm.* 119 | AutoTest.Net/ 120 | 121 | # Web workbench (sass) 122 | .sass-cache/ 123 | 124 | # Installshield output folder 125 | [Ee]xpress/ 126 | 127 | # DocProject is a documentation generator add-in 128 | DocProject/buildhelp/ 129 | DocProject/Help/*.HxT 130 | DocProject/Help/*.HxC 131 | DocProject/Help/*.hhc 132 | DocProject/Help/*.hhk 133 | DocProject/Help/*.hhp 134 | DocProject/Help/Html2 135 | DocProject/Help/html 136 | 137 | # Click-Once directory 138 | publish/ 139 | 140 | # Publish Web Output 141 | *.[Pp]ublish.xml 142 | *.azurePubxml 143 | # TODO: Comment the next line if you want to checkin your web deploy settings 144 | # but database connection strings (with potential passwords) will be unencrypted 145 | *.pubxml 146 | *.publishproj 147 | 148 | # Microsoft Azure Web App publish settings. Comment the next line if you want to 149 | # checkin your Azure Web App publish settings, but sensitive information contained 150 | # in these scripts will be unencrypted 151 | PublishScripts/ 152 | 153 | # NuGet Packages 154 | *.nupkg 155 | # The packages folder can be ignored because of Package Restore 156 | **/packages/* 157 | # except build/, which is used as an MSBuild target. 158 | !**/packages/build/ 159 | # Uncomment if necessary however generally it will be regenerated when needed 160 | #!**/packages/repositories.config 161 | # NuGet v3's project.json files produces more ignoreable files 162 | *.nuget.props 163 | *.nuget.targets 164 | 165 | # Microsoft Azure Build Output 166 | csx/ 167 | *.build.csdef 168 | 169 | # Microsoft Azure Emulator 170 | ecf/ 171 | rcf/ 172 | 173 | # Windows Store app package directories and files 174 | AppPackages/ 175 | BundleArtifacts/ 176 | Package.StoreAssociation.xml 177 | _pkginfo.txt 178 | 179 | # Visual Studio cache files 180 | # files ending in .cache can be ignored 181 | *.[Cc]ache 182 | # but keep track of directories ending in .cache 183 | !*.[Cc]ache/ 184 | 185 | # Others 186 | ClientBin/ 187 | ~$* 188 | *~ 189 | *.dbmdl 190 | *.dbproj.schemaview 191 | *.pfx 192 | *.publishsettings 193 | node_modules/ 194 | orleans.codegen.cs 195 | 196 | # Since there are multiple workflows, uncomment next line to ignore bower_components 197 | # (https://github.com/github/gitignore/pull/1529#issuecomment-104372622) 198 | #bower_components/ 199 | 200 | # RIA/Silverlight projects 201 | Generated_Code/ 202 | 203 | # Backup & report files from converting an old project file 204 | # to a newer Visual Studio version. Backup files are not needed, 205 | # because we have git ;-) 206 | _UpgradeReport_Files/ 207 | Backup*/ 208 | UpgradeLog*.XML 209 | UpgradeLog*.htm 210 | 211 | # SQL Server files 212 | *.mdf 213 | *.ldf 214 | 215 | # Business Intelligence projects 216 | *.rdl.data 217 | *.bim.layout 218 | *.bim_*.settings 219 | 220 | # Microsoft Fakes 221 | FakesAssemblies/ 222 | 223 | # GhostDoc plugin setting file 224 | *.GhostDoc.xml 225 | 226 | # Node.js Tools for Visual Studio 227 | .ntvs_analysis.dat 228 | 229 | # Visual Studio 6 build log 230 | *.plg 231 | 232 | # Visual Studio 6 workspace options file 233 | *.opt 234 | 235 | # Visual Studio LightSwitch build output 236 | **/*.HTMLClient/GeneratedArtifacts 237 | **/*.DesktopClient/GeneratedArtifacts 238 | **/*.DesktopClient/ModelManifest.xml 239 | **/*.Server/GeneratedArtifacts 240 | **/*.Server/ModelManifest.xml 241 | _Pvt_Extensions 242 | 243 | # Paket dependency manager 244 | .paket/paket.exe 245 | paket-files/ 246 | 247 | # FAKE - F# Make 248 | .fake/ 249 | 250 | # JetBrains Rider 251 | .idea/ 252 | *.sln.iml 253 | -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | # CosmosDB Emulator Dockerfile 2 | 3 | # Indicates that the windowsservercore image will be used as the base image. 4 | FROM microsoft/windowsservercore 5 | 6 | # Metadata indicating an image maintainer. 7 | MAINTAINER mominag@microsoft.com 8 | 9 | # Add the CosmosDB installer msi into the package 10 | ADD https://aka.ms/cosmosdb-emulator c:\\CosmosDBEmulator\\AzureCosmosDB.Emulator.msi 11 | 12 | # Copy misc scripts into the package 13 | COPY package_scripts\\startemu.cmd c:\\CosmosDBEmulator\\startemu.cmd 14 | COPY package_scripts\\getaddr.ps1 c:\\CosmosDBEmulator\\getaddr.ps1 15 | COPY package_scripts\\exportcert.ps1 c:\\CosmosDBEmulator\\exportcert.ps1 16 | COPY package_scripts\\importcert.ps1 c:\\CosmosDBEmulator\\importcert.ps1 17 | 18 | # Install the MSI 19 | RUN echo "Starting Installer" 20 | RUN powershell.exe -Command $ErrorActionPreference = 'Stop'; \ 21 | Start-Process 'msiexec.exe' -ArgumentList '/i','c:\CosmosDBEmulator\AzureCosmosDB.Emulator.msi','/qn' -Wait 22 | RUN echo "Installer Done" 23 | 24 | # Expose the required network ports 25 | EXPOSE 8081 26 | EXPOSE 8901 27 | EXPOSE 8902 28 | EXPOSE 10250 29 | EXPOSE 10251 30 | EXPOSE 10252 31 | EXPOSE 10253 32 | EXPOSE 10254 33 | EXPOSE 10255 34 | EXPOSE 10350 35 | 36 | # Start the interactive shell 37 | CMD [ "c:\\CosmosDBEmulator\\startemu.cmd" ] 38 | 39 | 40 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) Microsoft Corporation. All rights reserved. 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Azure Cosmos DB Emulator Docker Container 2 | 3 | This repository contains the scripts required to install and run the [Azure Cosmos DB Emulator](https://learn.microsoft.com/en-us/azure/cosmos-db/docker-emulator-windows) as a Docker container. 4 | 5 | You can fetch the image from Docker Hub by running `docker pull mcr.microsoft.com/cosmosdb/windows/azure-cosmos-emulator`. 6 | 7 | ## About the Azure Cosmos DB service 8 | [Azure Cosmos DB](https://docs.microsoft.com/azure/cosmos-db/introduction) is Microsoft's globally distributed, multi-model database. With the click of a button, Azure Cosmos DB enables you to elastically and independently scale throughput and storage across any number of Azure's geographic regions. It offers throughput, latency, availability, and consistency guarantees with comprehensive service level agreements (SLAs), something no other database service can offer. 9 | 10 | ## About the Azure Cosmos DB emulator 11 | 12 | The Azure Cosmos DB Emulator provides a local environment that emulates the Azure Cosmos DB service for development purposes. Using the emulator, you can develop and test your application locally, without creating an Azure subscription or incurring any costs. When you're satisfied with how your application is working in the Azure Cosmos DB Emulator, you can switch to using an Azure Cosmos DB account in the cloud. 13 | 14 | ## Running inside Docker 15 | 16 | The Azure Cosmos DB Emulator can be run on Docker Windows containers. The emulator does not work on Linux containers. 17 | 18 | Once you have [Docker for Windows](https://www.docker.com/docker-windows) installed, you can pull the Emulator image from Docker Hub by running the following command from your favorite shell (cmd.exe, PowerShell, etc.). 19 | 20 | ``` 21 | docker pull microsoft/azure-cosmosdb-emulator 22 | ``` 23 | To start the image, run the following commands. 24 | 25 | ``` 26 | md %LOCALAPPDATA%\CosmosDBEmulatorCert 2>nul 27 | docker run -v %LOCALAPPDATA%\CosmosDBEmulatorCert:c:\CosmosDBEmulator\CosmosDBEmulatorCert -P -t -i mcr.microsoft.com/cosmosdb/windows/azure-cosmos-emulator 28 | ``` 29 | 30 | The response looks similar to the following: 31 | 32 | ``` 33 | Starting Emulator 34 | Emulator Endpoint: https://172.20.229.193:8081/ 35 | Master Key: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw== 36 | Exporting SSL Certificate 37 | You can import the SSL certificate from an administrator command prompt on the host by running: 38 | cd /d %LOCALAPPDATA%\DocumentDBEmulatorCert 39 | powershell .\importcert.ps1 40 | -------------------------------------------------------------------------------------------------- 41 | Starting interactive shell 42 | ``` 43 | 44 | Closing the interactive shell once the Emulator has been started will shutdown the Emulator’s container. 45 | 46 | Use the endpoint and master key in from the response in your client and import the SSL certificate into your host. To import the SSL certificate, do the following from an admin command prompt: 47 | 48 | ``` 49 | cd %LOCALAPPDATA%\CosmosDBEmulatorCert 50 | powershell .\importcert.ps1 51 | ``` 52 | 53 | ## Developing against the emulator 54 | See [Developing against the emulator](https://learn.microsoft.com/en-us/azure/cosmos-db/docker-emulator-windows) for how to connect to the emulator using one of the supported APIs/SDKs. 55 | 56 | # Linux-based emulator (preview) 57 | The next generation of the Azure Cosmos DB emulator is entirely Linux-based and is available as a Docker container. It supports running on a wide variety of processors and operating systems, including Apple silicon and Microsoft ARM chips without any workarounds or virtual machines necessary. For more information, see documentation [here](https://aka.ms/CosmosVNextEmulator). 58 | 59 | ### Prerequisites 60 | 61 | - [Docker](https://www.docker.com/) 62 | 63 | ### Installation 64 | 65 | Get the Docker container image using `docker pull`. The container image is published to the [Microsoft Artifact Registry](https://mcr.microsoft.com/) as `mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview`. 66 | 67 | ```bash 68 | docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview 69 | ``` 70 | 71 | ### Running 72 | 73 | To run the container, use `docker run`. Afterwards, use `docker ps` to validate that the container is running. 74 | 75 | ```bash 76 | docker run --detach --publish 8081:8081 --publish 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview 77 | 78 | docker ps 79 | ``` 80 | 81 | ```output 82 | CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 83 | c1bb8cf53f8a mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview "/bin/bash -c /home/…" 5 seconds ago Up 5 seconds 0.0.0.0:1234->1234/tcp, :::1234->1234/tcp, 0.0.0.0:8081->8081/tcp, :::8081->8081/tcp 84 | ``` 85 | ### Reporting issues 86 | 87 | If you encounter any problems with using this version of the emulator, please open an issue in this GitHub repository and tag it with the label `cosmosEmulatorVnextPreview`. 88 | 89 | ### Checking for the current version 90 | 91 | Run the following command (*after you pulled the latest version*) to find if the version is current: 92 | 93 | ``` 94 | docker inspect mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview | grep Created 95 | ``` 96 | ``` 97 | "Created": "2024-12-16T20:23:52.276219413Z", 98 | ``` 99 | 100 | # Installing certificates for Java SDK 101 | 102 | When using the [Java SDK for Azure Cosmos DB](https://learn.microsoft.com/java/api/overview/azure/cosmos-readme?view=azure-java-stable) with the Azure Cosmos DB emulator, or the [linux based emulator](https://aka.ms/CosmosVNextEmulator) in https mode, it is necessary to install it's certificates to your local Java trust store. 103 | 104 | ### Get certificate 105 | 106 | In a `bash` window, run the following: 107 | 108 | ```bash 109 | # If the emulator was started with /AllowNetworkAccess, replace localhost with the actual IP address of it: 110 | EMULATOR_HOST=localhost 111 | EMULATOR_PORT=8081 112 | EMULATOR_CERT_PATH=/tmp/cosmos_emulator.cert 113 | openssl s_client -connect ${EMULATOR_HOST}:${EMULATOR_PORT} $EMULATOR_CERT_PATH 114 | ``` 115 | 116 | ### Install certificate 117 | 118 | Navigate to the directory of your java installation where `cacerts` file is located (replace below with correct directory): 119 | 120 | ```bash 121 | cd "C:/Program Files/Eclipse Adoptium/jdk-17.0.10.7-hotspot/bin" 122 | ``` 123 | 124 | Import the cert (you may be asked for a password, the default value is "changeit"): 125 | 126 | ```bash 127 | keytool -cacerts -importcert -alias cosmos_emulator -file $EMULATOR_CERT_PATH 128 | ``` 129 | 130 | If you get an error because the alias already exists, delete it and then run the above again: 131 | 132 | ```bash 133 | keytool -cacerts -delete -alias cosmos_emulator 134 | ``` 135 | 136 | 137 | -------------------------------------------------------------------------------- /SECURITY.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | ## Security 4 | 5 | Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/). 6 | 7 | If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://aka.ms/opensource/security/definition), please report it to us as described below. 8 | 9 | ## Reporting Security Issues 10 | 11 | **Please do not report security vulnerabilities through public GitHub issues.** 12 | 13 | Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://aka.ms/opensource/security/create-report). 14 | 15 | If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://aka.ms/opensource/security/pgpkey). 16 | 17 | You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://aka.ms/opensource/security/msrc). 18 | 19 | Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue: 20 | 21 | * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) 22 | * Full paths of source file(s) related to the manifestation of the issue 23 | * The location of the affected source code (tag/branch/commit or direct URL) 24 | * Any special configuration required to reproduce the issue 25 | * Step-by-step instructions to reproduce the issue 26 | * Proof-of-concept or exploit code (if possible) 27 | * Impact of the issue, including how an attacker might exploit the issue 28 | 29 | This information will help us triage your report more quickly. 30 | 31 | If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://aka.ms/opensource/security/bounty) page for more details about our active programs. 32 | 33 | ## Preferred Languages 34 | 35 | We prefer all communications to be in English. 36 | 37 | ## Policy 38 | 39 | Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://aka.ms/opensource/security/cvd). 40 | 41 | 42 | -------------------------------------------------------------------------------- /docs/opentelemetry.md: -------------------------------------------------------------------------------- 1 | # CosmosDB Emulator OpenTelemetry Integration 2 | 3 | This document provides instructions for using OpenTelemetry with CosmosDB Emulator to monitor and trace your application. OpenTelemetry provides a standardized approach for collecting telemetry data, including traces, metrics, and logs. 4 | 5 | ## What is OpenTelemetry (OTLP)? 6 | 7 | [OpenTelemetry](https://opentelemetry.io/) (OTLP) is an open-source observability framework that provides a collection of tools, APIs, and SDKs for instrumenting, generating, collecting, and exporting telemetry data. It's vendor-neutral and has broad industry support, making it an ideal choice for standardizing telemetry across your applications. 8 | 9 | OTLP (OpenTelemetry Protocol) is the protocol used by OpenTelemetry to transmit telemetry data between components. It's designed to be efficient and compatible with various backends. 10 | 11 | ## Configuration Options 12 | 13 | CosmosDB Emulator supports several telemetry options, which can be configured through environment variables or command-line flags when running the Docker container: 14 | 15 | | Flag | Environment Variable | Description | Default | 16 | |------|---------------------|-------------|---------| 17 | | `--enable-telemetry` | `ENABLE_TELEMETRY` | Enable telemetry collection | `true` | 18 | | `--enable-otlp` | `ENABLE_OTLP_EXPORTER` | Enable OTLP exporter for sending telemetry to external collectors | `false` | 19 | | `--enable-console` | `ENABLE_CONSOLE_EXPORTER` | Enable console output of telemetry data (useful for debugging) | `false` | 20 | | `--log-level` | `LOG_LEVEL` | Set logging verbosity level | `info` | 21 | 22 | ## Setting Up OpenTelemetry with Docker Compose 23 | 24 | The simplest way to set up OpenTelemetry with CosmosDB Emulator is using Docker Compose. This configuration automatically connects CosmosDB Emulator with Jaeger for distributed tracing and Prometheus for metrics collection. 25 | 26 | ### Sample Docker Compose Configuration 27 | 28 | Create a `docker-compose.yml` file with the following content: 29 | 30 | ```yaml 31 | services: 32 | jaeger: 33 | image: jaegertracing/jaeger:latest 34 | container_name: jaeger 35 | ports: 36 | - "16686:16686" # Jaeger UI 37 | - "4317:4317" # OTLP gRPC 38 | - "4318:4318" # OTLP HTTP 39 | networks: 40 | - cosmos-network 41 | 42 | prometheus: 43 | image: prom/prometheus:latest 44 | container_name: prometheus 45 | ports: 46 | - "9090:9090" 47 | volumes: 48 | - ./prometheus.yml:/etc/prometheus/prometheus.yml 49 | networks: 50 | - cosmos-network 51 | command: 52 | - '--config.file=/etc/prometheus/prometheus.yml' 53 | - '--web.enable-otlp-receiver' 54 | - '--storage.tsdb.path=/prometheus' 55 | 56 | pgcosmos: 57 | image: cosmosemulator:latest 58 | container_name: pgcosmos 59 | ports: 60 | - "8081:8081" 61 | - "1234:1234" 62 | - "9712:9712" # PostgreSQL metrics endpoint 63 | environment: 64 | - ENABLE_TELEMETRY=true 65 | - ENABLE_OTLP_EXPORTER=true 66 | - ENABLE_CONSOLE_EXPORTER=false 67 | networks: 68 | - cosmos-network 69 | 70 | networks: 71 | cosmos-network: 72 | ``` 73 | 74 | ### Prometheus Configuration 75 | 76 | Create a `prometheus.yml` file in the same directory as your `docker-compose.yml`: 77 | 78 | ```yaml 79 | global: 80 | scrape_interval: 15s 81 | 82 | scrape_configs: 83 | - job_name: 'otlp' 84 | scrape_interval: 5s 85 | static_configs: 86 | - targets: ['localhost:9090'] 87 | ``` 88 | 89 | ### Starting the Stack 90 | 91 | Start the complete observability stack: 92 | 93 | ```bash 94 | docker-compose up -d 95 | ``` 96 | 97 | ## Manual Setup with Docker 98 | 99 | If you prefer to run CosmosDB Emulator directly with Docker, you can use the following commands: 100 | 101 | ### 1. Start Jaeger 102 | 103 | ```bash 104 | docker run -d --name jaeger \ 105 | -p 16686:16686 \ 106 | -p 4317:4317 \ 107 | -p 4318:4318 \ 108 | jaegertracing/jaeger:latest 109 | ``` 110 | 111 | ### 2. Start Prometheus 112 | 113 | First, create a prometheus.yml configuration file: 114 | 115 | ```yaml 116 | global: 117 | scrape_interval: 15s 118 | 119 | scrape_configs: 120 | - job_name: 'otlp' 121 | scrape_interval: 5s 122 | static_configs: 123 | - targets: ['localhost:9090'] 124 | ``` 125 | 126 | Then start Prometheus: 127 | 128 | ```bash 129 | docker run -d --name prometheus \ 130 | -p 9090:9090 \ 131 | -v $(pwd)/prometheus.yml:/etc/prometheus/prometheus.yml \ 132 | prom/prometheus:latest \ 133 | --config.file=/etc/prometheus/prometheus.yml \ 134 | --web.enable-otlp-receiver 135 | ``` 136 | 137 | ### 3. Start CosmosDB Emulator with OpenTelemetry enabled 138 | 139 | ```bash 140 | docker run -d --name pgcosmos \ 141 | -p 8081:8081 \ 142 | -p 1234:1234 \ 143 | -p 9712:9712 \ 144 | --link jaeger \ 145 | --link prometheus \ 146 | -e ENABLE_TELEMETRY=true \ 147 | -e ENABLE_OTLP_EXPORTER=true \ 148 | -e ENABLE_CONSOLE_EXPORTER=false \ 149 | cosmosemulator:latest 150 | ``` 151 | 152 | ## Accessing the Monitoring UIs 153 | 154 | - **Jaeger UI**: http://localhost:16686 155 | - **Prometheus UI**: http://localhost:9090 156 | 157 | ## Trace Information 158 | 159 | CosmosDB Emulator includes comprehensive tracing for all Cosmos DB operations. When OTLP exporting is enabled, you'll see traces for the following operations: 160 | 161 | ### Document Operations 162 | - `CosmosDB.DocumentOperation.Create` 163 | - `CosmosDB.DocumentOperation.Replace` 164 | - `CosmosDB.DocumentOperation.Upsert` 165 | - `CosmosDB.DocumentOperation.Delete` 166 | - `CosmosDB.DocumentOperation.Read` 167 | - `CosmosDB.DocumentOperation.Batch` 168 | - `CosmosDB.DocumentOperation.Patch` 169 | 170 | ### Database Operations 171 | - `CosmosDB.Database.Create` 172 | - `CosmosDB.Database.Read` 173 | - `CosmosDB.Database.Delete` 174 | - `CosmosDB.Database.List` 175 | - `CosmosDB.Database.GetOrFind` 176 | 177 | ### Collection Operations 178 | - `CosmosDB.Collection.Create` 179 | - `CosmosDB.Collection.Read` 180 | - `CosmosDB.Collection.Delete` 181 | - `CosmosDB.Collection.List` 182 | 183 | ### Query Operations 184 | - `CosmosDB.Query.Execute` 185 | - `CosmosDB.Query.ReadQueryPlan` 186 | 187 | ### Other Operations 188 | - `CosmosDB.Document.ReadFeed` 189 | - `CosmosDB.DatabaseAccount.Read` 190 | - `CosmosDB.PartitionKeyRange.Read` 191 | - `CosmosDB.Offer.List` 192 | 193 | Each trace includes detailed information such as: 194 | - Database name 195 | - Collection name 196 | - Document ID (when applicable) 197 | - Operation type and resource type 198 | - HTTP method and path 199 | - For queries: the original query text and translated query 200 | - For queries with results: the number of items returned 201 | 202 | ## Enabling the Console Exporter 203 | 204 | The console exporter is useful for debugging telemetry issues. It prints telemetry data directly to the console logs. To enable it: 205 | 206 | ```bash 207 | docker run -d --name pgcosmos \ 208 | -p 8081:8081 \ 209 | -e ENABLE_TELEMETRY=true \ 210 | -e ENABLE_CONSOLE_EXPORTER=true \ 211 | cosmosemulator:latest 212 | ``` 213 | 214 | Then check the logs: 215 | 216 | ```bash 217 | docker logs pgcosmos 218 | ``` 219 | 220 | ## OpenTelemetry Collector Configuration 221 | 222 | CosmosDB Emulator uses the OpenTelemetry Collector for processing telemetry data. The default configuration is: 223 | 224 | ```yaml 225 | receivers: 226 | otlp: 227 | protocols: 228 | grpc: 229 | http: 230 | postgresql: 231 | endpoint: localhost:9712 232 | username: otel 233 | password: otel 234 | tls: 235 | insecure: true 236 | 237 | processors: 238 | batch: 239 | timeout: 1s 240 | send_batch_size: 1024 241 | 242 | exporters: 243 | debug: 244 | verbosity: detailed 245 | 246 | otlp/traces: 247 | endpoint: traces:4317 248 | tls: 249 | insecure: true 250 | 251 | otlphttp/metrics: 252 | endpoint: "http://metrics:9090/api/v1/otlp" 253 | tls: 254 | insecure: true 255 | 256 | service: 257 | pipelines: 258 | traces: 259 | receivers: [otlp] 260 | processors: [batch] 261 | exporters: [debug, otlp/traces] 262 | metrics: 263 | receivers: [postgresql, otlp] 264 | processors: [batch] 265 | exporters: [otlphttp/metrics] 266 | 267 | telemetry: 268 | logs: 269 | level: "WARN" 270 | metrics: 271 | level: "normal" 272 | ``` 273 | 274 | For custom configuration, you can override this file by mounting your own configuration file when running the container: 275 | 276 | ```bash 277 | docker run -d --name pgcosmos \ 278 | -v $(pwd)/custom-otel-config.yaml:/etc/otel/config.yaml \ 279 | -e ENABLE_TELEMETRY=true \ 280 | -e ENABLE_OTLP_EXPORTER=true \ 281 | cosmosemulator:latest 282 | ``` 283 | 284 | ## Troubleshooting (Dev) 285 | 286 | ### View OpenTelemetry Collector Logs 287 | 288 | To see the OpenTelemetry collector logs: 289 | 290 | ```bash 291 | docker exec -it pgcosmos cat /logs/otel/collector.log 292 | ``` 293 | 294 | ### Check OpenTelemetry User Setup 295 | 296 | The PostgreSQL metrics require that the "otel" user is properly set up. To verify: 297 | 298 | ```bash 299 | docker exec -it pgcosmos /scripts/setup_otel_user.sh 300 | ``` 301 | 302 | ### Ensure PostgreSQL is Ready 303 | 304 | Before the OpenTelemetry collector can collect metrics, PostgreSQL needs to be fully started: 305 | 306 | ```bash 307 | docker exec -it pgcosmos pg_isready -p 9712 -U cosmosdev -h /socket 308 | ``` 309 | 310 | ## Using with Kubernetes 311 | 312 | If you're running CosmosDB Emulator in Kubernetes, you can deploy the OpenTelemetry collector as a sidecar container: 313 | 314 | ```yaml 315 | apiVersion: apps/v1 316 | kind: Deployment 317 | metadata: 318 | name: pgcosmos 319 | spec: 320 | selector: 321 | matchLabels: 322 | app: pgcosmos 323 | template: 324 | metadata: 325 | labels: 326 | app: pgcosmos 327 | spec: 328 | containers: 329 | - name: pgcosmos 330 | image: cosmosemulator:latest 331 | env: 332 | - name: ENABLE_TELEMETRY 333 | value: "true" 334 | - name: ENABLE_OTLP_EXPORTER 335 | value: "true" 336 | - name: otel-collector 337 | image: otel/opentelemetry-collector-contrib:latest 338 | volumeMounts: 339 | - name: otel-config 340 | mountPath: /etc/otel 341 | volumes: 342 | - name: otel-config 343 | configMap: 344 | name: otel-config 345 | ``` 346 | 347 | ## Metrics Information 348 | 349 | CosmosDB Emulator exports the following metrics: 350 | 351 | - **Request Rates:** Shows the traffic patterns for different operation types 352 | - **Query Execution Times:** Measures the time taken to execute different queries 353 | - **Resource Utilization:** CPU, memory usage and connection pool metrics 354 | - **Error Rates:** Tracking of errors by type and endpoint 355 | 356 | These metrics are available through any metrics backend that supports OTLP and provides valuable insights into the database's performance and health. 357 | -------------------------------------------------------------------------------- /mk.cmd: -------------------------------------------------------------------------------- 1 | docker build -t cosmosdb_emulator . 2 | -------------------------------------------------------------------------------- /package_scripts/exportcert.ps1: -------------------------------------------------------------------------------- 1 | $pass = ConvertTo-SecureString -String "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==" -Force -AsPlainText 2 | $cert = Get-ChildItem cert:\LocalMachine\My | Where-Object {$_.FriendlyName -eq "DocumentDbEmulatorCertificate" } 3 | $output = Export-PfxCertificate -Cert $cert -FilePath c:\CosmosDBEmulator\CosmosDBEmulatorCert\CosmosDBEmulatorCert.pfx -Password $pass 4 | -------------------------------------------------------------------------------- /package_scripts/getaddr.ps1: -------------------------------------------------------------------------------- 1 | $addrObj = (Get-NetIPAddress -AddressFamily IPV4 -AddressState Preferred -PrefixOrigin Manual | Select IPAddress) 2 | $addr = $addrObj.IPAddress 3 | $result = "Emulator Endpoint: https://" + $addr + ":8081/" 4 | echo $result 5 | -------------------------------------------------------------------------------- /package_scripts/importcert.ps1: -------------------------------------------------------------------------------- 1 | $pass = ConvertTo-SecureString -String "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==" -Force -AsPlainText 2 | $output = Import-PfxCertificate -FilePath .\CosmosDBEmulatorCert.pfx cert:\localMachine\my -Password $pass 3 | $output = Import-PfxCertificate -FilePath .\CosmosDBEmulatorCert.pfx cert:\localMachine\root -Password $pass 4 | -------------------------------------------------------------------------------- /package_scripts/startemu.cmd: -------------------------------------------------------------------------------- 1 | @echo off 2 | echo Starting Emulator 3 | rem start /WAIT "" "c:\Program Files\CosmosDB Emulator\CosmosDB.Emulator.exe" /noui /GenKeyFile=c:\CosmosDBEmulator\keyfile.txt 4 | rem start "" "c:\Program Files\CosmosDB Emulator\CosmosDB.Emulator.exe" /noui /AllowNetworkAccess /NoFirewall /KeyFile=c:\CosmosDBEmulator\keyfile.txt 5 | rem echo Authorization key: 6 | rem type c:\CosmosDBEmulator\keyfile.txt 7 | start "" "c:\Program Files\Azure Cosmos DB Emulator\CosmosDB.Emulator.exe" /noui /AllowNetworkAccess /NoFirewall /Key=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw== 8 | powershell -File c:\CosmosDBEmulator\getaddr.ps1 9 | echo Master Key: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw== 10 | echo Exporting SSL Certificate 11 | powershell -File c:\CosmosDBEmulator\exportcert.ps1 12 | copy /y c:\CosmosDBEmulator\importcert.ps1 c:\CosmosDBEmulator\CosmosDBEmulatorCert >nul 13 | echo You can import the SSL certificate from an administrator command prompt on the host by running: 14 | echo cd /d ^%%LOCALAPPDATA^%%\CosmosDBEmulatorCert 15 | echo powershell .\importcert.ps1 16 | echo -------------------------------------------------------------------------------------------------- 17 | echo Starting interactive shell 18 | cmd /K 19 | -------------------------------------------------------------------------------- /run.cmd: -------------------------------------------------------------------------------- 1 | @echo off 2 | md %LOCALAPPDATA%\CosmosDBEmulatorCert 2>nul 3 | docker run -v %LOCALAPPDATA%\CosmosDBEmulatorCert:c:\CosmosDBEmulator\CosmosDBEmulatorCert -P -t -i cosmosdb_emulator 4 | --------------------------------------------------------------------------------