readme.md

CompanionApp

CompanionApp is a .NET Blazor application that is meant to be deployed as a container app. On startup, it completes setup for a proxy by creating the configuration settings. It is also meant to be usued to configure the running settings. When not needed, it is safe to stop the service and the proxy will continue operation uninterrupted.

Once deployed, you can follow the quick guides below for your scenario.

Deployment	Configuration updates	Request testing
Prepare and deploy SimpleL7Proxy	Change an existing proxy's settings	Send requests and inspect results

Set up CompanionApp

The default settings in the file should be sufficient, however you want to override the default values you can update either settings. If you deployed to Azure Container Apps, the settings will be in the Azure Portal for the Container Environment variables. If running locally from the repo, the application configuration file is located in the application root folder at: src/CompanionApp.
You will want to configure the app for your environment so that you don't have to keep editing them in the UI. These settings are stored in your local src/CompanionApp/appsettings.json or src/CompanionApp/appsettings.Development.json file. As a best practice, your local changes should be made to src/CompanionApp/appsettings.Development.json as it distingueshes your settings vs the repo settings. If it doesn't already exist, create a new file and start with a copy of the CompanionApp section:

{
	"CompanionApp": {
		"AppConfigurationEndpoint": "https://nvm2-tc26-appcfg.azconfig.io",
		"AppConfigurationLabel": "ACA-L7-2",
		// Copy other sections as needed
	}
}

The settings below are all under CompanionApp. Each description explains what the setting controls and why you might customize it for your scenario.

Connection and request defaults

• AppConfigurationEndpoint: The HTTPS URL of the Azure App Configuration store you want to edit, ending in .azconfig.io. Use your store's endpoint, or leave it empty when you aren't using the configuration editor.
• AppConfigurationLabel: The exact, case-sensitive label your proxy reads from that store. Match the proxy's label, or leave it empty for unlabeled settings.
• ServerBaseUrl: The base URL of your deployed proxy or backend for request testing. Change it when switching environments, or use a local URL such as http://localhost:8000 for a local proxy.
• AuthorizationHeaderName: The request header used to send your API key or token, such as S7P-KEY, api-key, or Authorization. Match the header your endpoint expects; this is the name, not the credential.
• AuthorizationHeaderPrefix: The prefix for token authentication, normally Bearer. This is not an API key or access token; choose the authentication mode and supply the credential in the request form.
• UserHeaderName: The request header that carries the selected user identity. Use X-UserID or the header name your proxy is configured to read.
• PriorityKeyHeader: The request header that carries the selected priority key. Use S7PPriorityKey or your proxy's configured header name; the proxy determines how that key maps to a priority.

Saved requests and conversations

History controls storage for saved request/response records, while Conversations controls storage for multi-turn chat sessions. You can configure them independently; the fields below apply inside either section, for example History.Mode and Conversations.Mode.

• Mode: Where to save the records: Disk, BlobStorage, or CosmosDb. Keep Disk for local use without an Azure storage dependency, or choose a cloud backend when you need records stored outside the app's local filesystem.
• DiskPath: The directory used in Disk mode. Relative paths resolve from the app's content root; keep data/history and data/conversations, or choose other writable directories.
• StorageAccountName: The Azure Storage account used in BlobStorage mode. Enter the account name, not its URL or a connection string.
• BlobContainerName: The container within that storage account used in BlobStorage mode. Use history and conversations, or set these to your own container names.
• CosmosAccount: The Cosmos DB account used in CosmosDb mode. Enter the account name or its full endpoint URL, not an account key.
• CosmosDatabase: The database within that Cosmos DB account. The supplied value is chat-tester; keep your existing database name when you want to continue reading previously saved data.
• CosmosContainer: The container within that database used for the records. Use history and conversations, or set these to your own container names.

Only the fields for the selected backend are used. Blob Storage and Cosmos DB authenticate with CompanionApp's Azure identity, which needs access to the selected storage resources.

Event Hub monitoring

EventHubMonitor configures the shared event feed used by EventHub Monitor, Insights, and Tokenomics. The fields below belong inside CompanionApp.EventHubMonitor.

• eventhub_enabled: Whether CompanionApp connects to the live Event Hub. Set it to false to disable live reading; local-file import still runs when LocalFilePath is set.
• LocalFilePath: An optional JSON event-log file to import at startup. Use an absolute path, or set it to "" to skip import; relative paths resolve from the running app's output directory, not its content root.
• ConnectionString: An Event Hub namespace connection string with receive/listen access, for connection-string authentication. Leave it empty to use an Azure identity instead, and keep credentials out of source control.
• EventHubName: The name of the Event Hub your proxy publishes to. This is the hub name, not the namespace name.
• EventHubNamespace: The namespace hostname ending in .servicebus.windows.net, used for Azure-identity authentication. Set it along with EventHubName when ConnectionString is empty.
• ConsumerGroup: The existing consumer group CompanionApp reads through. Use the built-in $Default group or a group created for this reader; this setting does not create a group.
• CheckpointStorage: Not used by the current reader. Leave it empty; setting a value does not enable saved checkpoints.
• StartPosition: Where reading begins when the reader starts. Use latest for new events or earliest to also read retained events; the reader does not resume from a saved checkpoint after a restart.
• RefreshSeconds: How often the monitoring pages refresh, in seconds. A value of 5 refreshes the views every five seconds; it does not control how often the proxy publishes events.

See Event Hub setup for the required permissions, authentication choices, and live-telemetry checks.

Sign in for Azure workflows

If your workflow accesses Azure, sign in locally before you start CompanionApp:

az login
export AZURE_TOKEN_CREDENTIALS=AzureCliCredential

The export command tells DefaultAzureCredential to use your Azure CLI identity. It doesn't grant any permissions. Check the deployment guide, configuration prerequisites, or request-testing prerequisites for the roles your workflow needs.

If you host CompanionApp in Azure with a managed identity, do not set AZURE_TOKEN_CREDENTIALS=AzureCliCredential.

Start the app

From the CompanionApp directory, run:

dotnet restore
dotnet run

To start the UI without App Configuration startup access or the Event Hub reader, run dotnet run -- --uionly. This skips App Configuration loading and label creation, live Event Hub consumption, and Event Hub local-file import even when they are configured. The startup log confirms that UI-only mode is active.

This flag does not block Azure actions you explicitly initiate in the UI or change the configured history and conversation storage modes. Keep those modes set to Disk when you do not want cloud storage access.

To read Tokenomics summaries from Event Hub, configure the EventHubMonitor settings above and run dotnet run without --uionly or --run. Connection-string authentication requires receive/listen access; Azure identity authentication requires Azure Event Hubs Data Receiver access. The existing EVENTHUB_NAMESPACE, EVENTHUB_NAME, EVENTHUB_CONNECTIONSTRING, and EVENTHUB_CONSUMER_GROUP environment overrides also apply.

Open /tokenomics and publish proxy S7P-Tokenomics summaries with RecordKind equal to RequestOutcome or PolicyDecision. The dashboard replaces sample data when the configured reader starts and publishes buffered summaries once per second. Ordinary Tokenomics diagnostic logs and unrelated event types do not contribute; malformed summaries are logged and skipped without stopping consumption.

The Hourly, Daily, and Monthly controls apply one UTC calendar period to every dashboard widget. Hourly is selected by default and shows all 60 minutes in the current hour; Daily shows all 24 hours today; Monthly shows every day in the current month. Empty chart buckets remain visible with zero usage. Live periods use each summary's TimestampUtc and refresh idle data every minute. Historical replay periods are anchored to the latest replayed event.

The live dashboard aggregates the latest 10,000 valid summary records received by this process, across all partitions. Totals and deduplication apply only to that retained window, not lifetime usage. StartPosition=latest requires new events after startup; use earliest to include retained Event Hub events. Restarting resets the in-memory window and reads from the configured start position; no checkpoints are saved. A configured LocalFilePath import also feeds Tokenomics before live consumption.

To replay an NDJSON event file locally instead, run from this directory:

dotnet run -- --uionly --run events /absolute/path/tokenomics-summary-events.ndjson

The whole file is validated before startup. Replay replaces synthetic data immediately, applies ten events each second (a smaller final batch is allowed), and stops at EOF without looping. The final dashboard remains available at /tokenomics; stopping the app cancels replay safely. Events are not published to Azure. --uionly is optional and independently skips App Configuration startup access.

Both sources use the same validation and aggregation rules. Request counts use distinct MID values; success rate uses HTTP outcomes only. Policy Actions counts recorded policy decisions, including None and Bypass; 429 Throttles counts distinct requests with a throttle decision or HTTP 429. Cached input is a subset of input, not additional tokens. Spend uses the current App Configuration label's saved Warm:Tokenomics:Options model prices: non-cached input, cached input, and output tokens use their corresponding USD-per-token rates, and unlisted models are excluded. Spend remains unavailable when the current label has no valid model prices. Quota bars compare the selected period's token usage with HourlyTokenLimit, DailyTokenLimit, or MonthlyTokenLimit from those same saved settings. A missing or nonpositive period limit leaves quota unavailable. Events contain no previous-period data, so percentage changes are omitted. File replay does not start the Event Hub reader. UI-only mode and unconfigured or disabled readers retain synthetic Tokenomics updates when no file replay or local import is active.

Open the URL shown in the terminal. The included launch profiles use:

• http://localhost:5259
• https://localhost:7117

The launch profiles set ASPNETCORE_ENVIRONMENT=Development. Restart CompanionApp whenever you change your local settings.

Tip

If your changes don't appear, check the exact property name, the settings file for the active environment, and any environment-variable overrides. For request defaults, also check your Development model files and saved User Preferences.

Deploy SimpleL7Proxy

The Deploy SimpleL7Proxy guide walks you through the prerequisites and Azure roles, then shows you how to deploy, verify, and troubleshoot your setup.

Update Azure App Configuration

Follow Update Azure App Configuration to connect to your store, edit and publish settings, and check that your proxy has picked up the changes. The guide also covers prerequisites and troubleshooting.

Test HTTP and LLM endpoints

Follow Test HTTP and LLM endpoints to check what you need, send requests, and inspect the results. The guide also covers saved history, optional telemetry, and troubleshooting.