diff --git a/docs/docset.yml b/docs/docset.yml new file mode 100644 index 000000000..cfc068c8e --- /dev/null +++ b/docs/docset.yml @@ -0,0 +1,492 @@ +project: 'APM .NET agent docs' +cross_links: + - apm-agent-rum-js + - beats + - docs-content + - ecs + - ecs-dotnet + - ecs-logging + - elasticsearch +toc: + - toc: reference + - toc: release-notes +subs: + ref: "https://www.elastic.co/guide/en/elasticsearch/reference/current" + ref-bare: "https://www.elastic.co/guide/en/elasticsearch/reference" + ref-8x: "https://www.elastic.co/guide/en/elasticsearch/reference/8.1" + ref-80: "https://www.elastic.co/guide/en/elasticsearch/reference/8.0" + ref-7x: "https://www.elastic.co/guide/en/elasticsearch/reference/7.17" + ref-70: "https://www.elastic.co/guide/en/elasticsearch/reference/7.0" + ref-60: "https://www.elastic.co/guide/en/elasticsearch/reference/6.0" + ref-64: "https://www.elastic.co/guide/en/elasticsearch/reference/6.4" + xpack-ref: "https://www.elastic.co/guide/en/x-pack/6.2" + logstash-ref: "https://www.elastic.co/guide/en/logstash/current" + kibana-ref: "https://www.elastic.co/guide/en/kibana/current" + kibana-ref-all: "https://www.elastic.co/guide/en/kibana" + beats-ref-root: "https://www.elastic.co/guide/en/beats" + beats-ref: "https://www.elastic.co/guide/en/beats/libbeat/current" + beats-ref-60: "https://www.elastic.co/guide/en/beats/libbeat/6.0" + beats-ref-63: "https://www.elastic.co/guide/en/beats/libbeat/6.3" + beats-devguide: "https://www.elastic.co/guide/en/beats/devguide/current" + auditbeat-ref: "https://www.elastic.co/guide/en/beats/auditbeat/current" + packetbeat-ref: "https://www.elastic.co/guide/en/beats/packetbeat/current" + metricbeat-ref: "https://www.elastic.co/guide/en/beats/metricbeat/current" + filebeat-ref: "https://www.elastic.co/guide/en/beats/filebeat/current" + functionbeat-ref: "https://www.elastic.co/guide/en/beats/functionbeat/current" + winlogbeat-ref: "https://www.elastic.co/guide/en/beats/winlogbeat/current" + heartbeat-ref: "https://www.elastic.co/guide/en/beats/heartbeat/current" + journalbeat-ref: "https://www.elastic.co/guide/en/beats/journalbeat/current" + ingest-guide: "https://www.elastic.co/guide/en/ingest/current" + fleet-guide: "https://www.elastic.co/guide/en/fleet/current" + apm-guide-ref: "https://www.elastic.co/guide/en/apm/guide/current" + apm-guide-7x: "https://www.elastic.co/guide/en/apm/guide/7.17" + apm-app-ref: "https://www.elastic.co/guide/en/kibana/current" + apm-agents-ref: "https://www.elastic.co/guide/en/apm/agent" + apm-android-ref: "https://www.elastic.co/guide/en/apm/agent/android/current" + apm-py-ref: "https://www.elastic.co/guide/en/apm/agent/python/current" + apm-py-ref-3x: "https://www.elastic.co/guide/en/apm/agent/python/3.x" + apm-node-ref-index: "https://www.elastic.co/guide/en/apm/agent/nodejs" + apm-node-ref: "https://www.elastic.co/guide/en/apm/agent/nodejs/current" + apm-node-ref-1x: "https://www.elastic.co/guide/en/apm/agent/nodejs/1.x" + apm-rum-ref: "https://www.elastic.co/guide/en/apm/agent/rum-js/current" + apm-ruby-ref: "https://www.elastic.co/guide/en/apm/agent/ruby/current" + apm-java-ref: "https://www.elastic.co/guide/en/apm/agent/java/current" + apm-go-ref: "https://www.elastic.co/guide/en/apm/agent/go/current" + apm-dotnet-ref: "https://www.elastic.co/guide/en/apm/agent/dotnet/current" + apm-php-ref: "https://www.elastic.co/guide/en/apm/agent/php/current" + apm-ios-ref: "https://www.elastic.co/guide/en/apm/agent/swift/current" + apm-lambda-ref: "https://www.elastic.co/guide/en/apm/lambda/current" + apm-attacher-ref: "https://www.elastic.co/guide/en/apm/attacher/current" + docker-logging-ref: "https://www.elastic.co/guide/en/beats/loggingplugin/current" + esf-ref: "https://www.elastic.co/guide/en/esf/current" + kinesis-firehose-ref: "https://www.elastic.co/guide/en/kinesis/{{kinesis_version}}" + estc-welcome-current: "https://www.elastic.co/guide/en/starting-with-the-elasticsearch-platform-and-its-solutions/current" + estc-welcome: "https://www.elastic.co/guide/en/starting-with-the-elasticsearch-platform-and-its-solutions/current" + estc-welcome-all: "https://www.elastic.co/guide/en/starting-with-the-elasticsearch-platform-and-its-solutions" + hadoop-ref: "https://www.elastic.co/guide/en/elasticsearch/hadoop/current" + stack-ref: "https://www.elastic.co/guide/en/elastic-stack/current" + stack-ref-67: "https://www.elastic.co/guide/en/elastic-stack/6.7" + stack-ref-68: "https://www.elastic.co/guide/en/elastic-stack/6.8" + stack-ref-70: "https://www.elastic.co/guide/en/elastic-stack/7.0" + stack-ref-80: "https://www.elastic.co/guide/en/elastic-stack/8.0" + stack-ov: "https://www.elastic.co/guide/en/elastic-stack-overview/current" + stack-gs: "https://www.elastic.co/guide/en/elastic-stack-get-started/current" + stack-gs-current: "https://www.elastic.co/guide/en/elastic-stack-get-started/current" + javaclient: "https://www.elastic.co/guide/en/elasticsearch/client/java-api/current" + java-api-client: "https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current" + java-rest: "https://www.elastic.co/guide/en/elasticsearch/client/java-rest/current" + jsclient: "https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current" + jsclient-current: "https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current" + es-ruby-client: "https://www.elastic.co/guide/en/elasticsearch/client/ruby-api/current" + es-dotnet-client: "https://www.elastic.co/guide/en/elasticsearch/client/net-api/current" + es-php-client: "https://www.elastic.co/guide/en/elasticsearch/client/php-api/current" + es-python-client: "https://www.elastic.co/guide/en/elasticsearch/client/python-api/current" + defguide: "https://www.elastic.co/guide/en/elasticsearch/guide/2.x" + painless: "https://www.elastic.co/guide/en/elasticsearch/painless/current" + plugins: "https://www.elastic.co/guide/en/elasticsearch/plugins/current" + plugins-8x: "https://www.elastic.co/guide/en/elasticsearch/plugins/8.1" + plugins-7x: "https://www.elastic.co/guide/en/elasticsearch/plugins/7.17" + plugins-6x: "https://www.elastic.co/guide/en/elasticsearch/plugins/6.8" + glossary: "https://www.elastic.co/guide/en/elastic-stack-glossary/current" + upgrade_guide: "https://www.elastic.co/products/upgrade_guide" + blog-ref: "https://www.elastic.co/blog/" + curator-ref: "https://www.elastic.co/guide/en/elasticsearch/client/curator/current" + curator-ref-current: "https://www.elastic.co/guide/en/elasticsearch/client/curator/current" + metrics-ref: "https://www.elastic.co/guide/en/metrics/current" + metrics-guide: "https://www.elastic.co/guide/en/metrics/guide/current" + logs-ref: "https://www.elastic.co/guide/en/logs/current" + logs-guide: "https://www.elastic.co/guide/en/logs/guide/current" + uptime-guide: "https://www.elastic.co/guide/en/uptime/current" + observability-guide: "https://www.elastic.co/guide/en/observability/current" + observability-guide-all: "https://www.elastic.co/guide/en/observability" + siem-guide: "https://www.elastic.co/guide/en/siem/guide/current" + security-guide: "https://www.elastic.co/guide/en/security/current" + security-guide-all: "https://www.elastic.co/guide/en/security" + endpoint-guide: "https://www.elastic.co/guide/en/endpoint/current" + sql-odbc: "https://www.elastic.co/guide/en/elasticsearch/sql-odbc/current" + ecs-ref: "https://www.elastic.co/guide/en/ecs/current" + ecs-logging-ref: "https://www.elastic.co/guide/en/ecs-logging/overview/current" + ecs-logging-go-logrus-ref: "https://www.elastic.co/guide/en/ecs-logging/go-logrus/current" + ecs-logging-go-zap-ref: "https://www.elastic.co/guide/en/ecs-logging/go-zap/current" + ecs-logging-go-zerolog-ref: "https://www.elastic.co/guide/en/ecs-logging/go-zap/current" + ecs-logging-java-ref: "https://www.elastic.co/guide/en/ecs-logging/java/current" + ecs-logging-dotnet-ref: "https://www.elastic.co/guide/en/ecs-logging/dotnet/current" + ecs-logging-nodejs-ref: "https://www.elastic.co/guide/en/ecs-logging/nodejs/current" + ecs-logging-php-ref: "https://www.elastic.co/guide/en/ecs-logging/php/current" + ecs-logging-python-ref: "https://www.elastic.co/guide/en/ecs-logging/python/current" + ecs-logging-ruby-ref: "https://www.elastic.co/guide/en/ecs-logging/ruby/current" + ml-docs: "https://www.elastic.co/guide/en/machine-learning/current" + eland-docs: "https://www.elastic.co/guide/en/elasticsearch/client/eland/current" + eql-ref: "https://eql.readthedocs.io/en/latest/query-guide" + extendtrial: "https://www.elastic.co/trialextension" + wikipedia: "https://en.wikipedia.org/wiki" + forum: "https://discuss.elastic.co/" + xpack-forum: "https://discuss.elastic.co/c/50-x-pack" + security-forum: "https://discuss.elastic.co/c/x-pack/shield" + watcher-forum: "https://discuss.elastic.co/c/x-pack/watcher" + monitoring-forum: "https://discuss.elastic.co/c/x-pack/marvel" + graph-forum: "https://discuss.elastic.co/c/x-pack/graph" + apm-forum: "https://discuss.elastic.co/c/apm" + enterprise-search-ref: "https://www.elastic.co/guide/en/enterprise-search/current" + app-search-ref: "https://www.elastic.co/guide/en/app-search/current" + workplace-search-ref: "https://www.elastic.co/guide/en/workplace-search/current" + enterprise-search-node-ref: "https://www.elastic.co/guide/en/enterprise-search-clients/enterprise-search-node/current" + enterprise-search-php-ref: "https://www.elastic.co/guide/en/enterprise-search-clients/php/current" + enterprise-search-python-ref: "https://www.elastic.co/guide/en/enterprise-search-clients/python/current" + enterprise-search-ruby-ref: "https://www.elastic.co/guide/en/enterprise-search-clients/ruby/current" + elastic-maps-service: "https://maps.elastic.co" + integrations-docs: "https://docs.elastic.co/en/integrations" + integrations-devguide: "https://www.elastic.co/guide/en/integrations-developer/current" + time-units: "https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#time-units" + byte-units: "https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#byte-units" + apm-py-ref-v: "https://www.elastic.co/guide/en/apm/agent/python/current" + apm-node-ref-v: "https://www.elastic.co/guide/en/apm/agent/nodejs/current" + apm-rum-ref-v: "https://www.elastic.co/guide/en/apm/agent/rum-js/current" + apm-ruby-ref-v: "https://www.elastic.co/guide/en/apm/agent/ruby/current" + apm-java-ref-v: "https://www.elastic.co/guide/en/apm/agent/java/current" + apm-go-ref-v: "https://www.elastic.co/guide/en/apm/agent/go/current" + apm-ios-ref-v: "https://www.elastic.co/guide/en/apm/agent/swift/current" + apm-dotnet-ref-v: "https://www.elastic.co/guide/en/apm/agent/dotnet/current" + apm-php-ref-v: "https://www.elastic.co/guide/en/apm/agent/php/current" + ecloud: "Elastic Cloud" + esf: "Elastic Serverless Forwarder" + ess: "Elasticsearch Service" + ece: "Elastic Cloud Enterprise" + eck: "Elastic Cloud on Kubernetes" + serverless-full: "Elastic Cloud Serverless" + serverless-short: "Serverless" + es-serverless: "Elasticsearch Serverless" + es3: "Elasticsearch Serverless" + obs-serverless: "Elastic Observability Serverless" + sec-serverless: "Elastic Security Serverless" + serverless-docs: "https://docs.elastic.co/serverless" + cloud: "https://www.elastic.co/guide/en/cloud/current" + ess-utm-params: "?page=docs&placement=docs-body" + ess-baymax: "?page=docs&placement=docs-body" + ess-trial: "https://cloud.elastic.co/registration?page=docs&placement=docs-body" + ess-product: "https://www.elastic.co/cloud/elasticsearch-service?page=docs&placement=docs-body" + ess-console: "https://cloud.elastic.co?page=docs&placement=docs-body" + ess-console-name: "Elasticsearch Service Console" + ess-deployments: "https://cloud.elastic.co/deployments?page=docs&placement=docs-body" + ece-ref: "https://www.elastic.co/guide/en/cloud-enterprise/current" + eck-ref: "https://www.elastic.co/guide/en/cloud-on-k8s/current" + ess-leadin: "You can run Elasticsearch on your own hardware or use our hosted Elasticsearch Service that is available on AWS, GCP, and Azure. https://cloud.elastic.co/registration{ess-utm-params}[Try the Elasticsearch Service for free]." + ess-leadin-short: "Our hosted Elasticsearch Service is available on AWS, GCP, and Azure, and you can https://cloud.elastic.co/registration{ess-utm-params}[try it for free]." + ess-icon: "image:https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg[link=\"https://cloud.elastic.co/registration{ess-utm-params}\", title=\"Supported on Elasticsearch Service\"]" + ece-icon: "image:https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud_ece.svg[link=\"https://cloud.elastic.co/registration{ess-utm-params}\", title=\"Supported on Elastic Cloud Enterprise\"]" + cloud-only: "This feature is designed for indirect use by https://cloud.elastic.co/registration{ess-utm-params}[Elasticsearch Service], https://www.elastic.co/guide/en/cloud-enterprise/{ece-version-link}[Elastic Cloud Enterprise], and https://www.elastic.co/guide/en/cloud-on-k8s/current[Elastic Cloud on Kubernetes]. Direct use is not supported." + ess-setting-change: "image:https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg[link=\"{ess-trial}\", title=\"Supported on {ess}\"] indicates a change to a supported https://www.elastic.co/guide/en/cloud/current/ec-add-user-settings.html[user setting] for Elasticsearch Service." + ess-skip-section: "If you use Elasticsearch Service, skip this section. Elasticsearch Service handles these changes for you." + api-cloud: "https://www.elastic.co/docs/api/doc/cloud" + api-ece: "https://www.elastic.co/docs/api/doc/cloud-enterprise" + api-kibana-serverless: "https://www.elastic.co/docs/api/doc/serverless" + es-feature-flag: "This feature is in development and not yet available for use. This documentation is provided for informational purposes only." + es-ref-dir: "'{{elasticsearch-root}}/docs/reference'" + apm-app: "APM app" + uptime-app: "Uptime app" + synthetics-app: "Synthetics app" + logs-app: "Logs app" + metrics-app: "Metrics app" + infrastructure-app: "Infrastructure app" + siem-app: "SIEM app" + security-app: "Elastic Security app" + ml-app: "Machine Learning" + dev-tools-app: "Dev Tools" + ingest-manager-app: "Ingest Manager" + stack-manage-app: "Stack Management" + stack-monitor-app: "Stack Monitoring" + alerts-ui: "Alerts and Actions" + rules-ui: "Rules" + rac-ui: "Rules and Connectors" + connectors-ui: "Connectors" + connectors-feature: "Actions and Connectors" + stack-rules-feature: "Stack Rules" + user-experience: "User Experience" + ems: "Elastic Maps Service" + ems-init: "EMS" + hosted-ems: "Elastic Maps Server" + ipm-app: "Index Pattern Management" + ingest-pipelines: "ingest pipelines" + ingest-pipelines-app: "Ingest Pipelines" + ingest-pipelines-cap: "Ingest pipelines" + ls-pipelines: "Logstash pipelines" + ls-pipelines-app: "Logstash Pipelines" + maint-windows: "maintenance windows" + maint-windows-app: "Maintenance Windows" + maint-windows-cap: "Maintenance windows" + custom-roles-app: "Custom Roles" + data-source: "data view" + data-sources: "data views" + data-source-caps: "Data View" + data-sources-caps: "Data Views" + data-source-cap: "Data view" + data-sources-cap: "Data views" + project-settings: "Project settings" + manage-app: "Management" + index-manage-app: "Index Management" + data-views-app: "Data Views" + rules-app: "Rules" + saved-objects-app: "Saved Objects" + tags-app: "Tags" + api-keys-app: "API keys" + transforms-app: "Transforms" + connectors-app: "Connectors" + files-app: "Files" + reports-app: "Reports" + maps-app: "Maps" + alerts-app: "Alerts" + crawler: "Enterprise Search web crawler" + ents: "Enterprise Search" + app-search-crawler: "App Search web crawler" + agent: "Elastic Agent" + agents: "Elastic Agents" + fleet: "Fleet" + fleet-server: "Fleet Server" + integrations-server: "Integrations Server" + ingest-manager: "Ingest Manager" + ingest-management: "ingest management" + package-manager: "Elastic Package Manager" + integrations: "Integrations" + package-registry: "Elastic Package Registry" + artifact-registry: "Elastic Artifact Registry" + aws: "AWS" + stack: "Elastic Stack" + xpack: "X-Pack" + es: "Elasticsearch" + kib: "Kibana" + esms: "Elastic Stack Monitoring Service" + esms-init: "ESMS" + ls: "Logstash" + beats: "Beats" + auditbeat: "Auditbeat" + filebeat: "Filebeat" + heartbeat: "Heartbeat" + metricbeat: "Metricbeat" + packetbeat: "Packetbeat" + winlogbeat: "Winlogbeat" + functionbeat: "Functionbeat" + journalbeat: "Journalbeat" + es-sql: "Elasticsearch SQL" + esql: "ES|QL" + elastic-agent: "Elastic Agent" + k8s: "Kubernetes" + log-driver-long: "Elastic Logging Plugin for Docker" + security: "X-Pack security" + security-features: "security features" + operator-feature: "operator privileges feature" + es-security-features: "Elasticsearch security features" + stack-security-features: "Elastic Stack security features" + endpoint-sec: "Endpoint Security" + endpoint-cloud-sec: "Endpoint and Cloud Security" + elastic-defend: "Elastic Defend" + elastic-sec: "Elastic Security" + elastic-endpoint: "Elastic Endpoint" + swimlane: "Swimlane" + sn: "ServiceNow" + sn-itsm: "ServiceNow ITSM" + sn-itom: "ServiceNow ITOM" + sn-sir: "ServiceNow SecOps" + jira: "Jira" + ibm-r: "IBM Resilient" + webhook: "Webhook" + webhook-cm: "Webhook - Case Management" + opsgenie: "Opsgenie" + bedrock: "Amazon Bedrock" + gemini: "Google Gemini" + hive: "TheHive" + monitoring: "X-Pack monitoring" + monitor-features: "monitoring features" + stack-monitor-features: "Elastic Stack monitoring features" + watcher: "Watcher" + alert-features: "alerting features" + reporting: "X-Pack reporting" + report-features: "reporting features" + graph: "X-Pack graph" + graph-features: "graph analytics features" + searchprofiler: "Search Profiler" + xpackml: "X-Pack machine learning" + ml: "machine learning" + ml-cap: "Machine learning" + ml-init: "ML" + ml-features: "machine learning features" + stack-ml-features: "Elastic Stack machine learning features" + ccr: "cross-cluster replication" + ccr-cap: "Cross-cluster replication" + ccr-init: "CCR" + ccs: "cross-cluster search" + ccs-cap: "Cross-cluster search" + ccs-init: "CCS" + ilm: "index lifecycle management" + ilm-cap: "Index lifecycle management" + ilm-init: "ILM" + dlm: "data lifecycle management" + dlm-cap: "Data lifecycle management" + dlm-init: "DLM" + search-snap: "searchable snapshot" + search-snaps: "searchable snapshots" + search-snaps-cap: "Searchable snapshots" + slm: "snapshot lifecycle management" + slm-cap: "Snapshot lifecycle management" + slm-init: "SLM" + rollup-features: "data rollup features" + ipm: "index pattern management" + ipm-cap: "Index pattern" + rollup: "rollup" + rollup-cap: "Rollup" + rollups: "rollups" + rollups-cap: "Rollups" + rollup-job: "rollup job" + rollup-jobs: "rollup jobs" + rollup-jobs-cap: "Rollup jobs" + dfeed: "datafeed" + dfeeds: "datafeeds" + dfeed-cap: "Datafeed" + dfeeds-cap: "Datafeeds" + ml-jobs: "machine learning jobs" + ml-jobs-cap: "Machine learning jobs" + anomaly-detect: "anomaly detection" + anomaly-detect-cap: "Anomaly detection" + anomaly-job: "anomaly detection job" + anomaly-jobs: "anomaly detection jobs" + anomaly-jobs-cap: "Anomaly detection jobs" + dataframe: "data frame" + dataframes: "data frames" + dataframe-cap: "Data frame" + dataframes-cap: "Data frames" + watcher-transform: "payload transform" + watcher-transforms: "payload transforms" + watcher-transform-cap: "Payload transform" + watcher-transforms-cap: "Payload transforms" + transform: "transform" + transforms: "transforms" + transform-cap: "Transform" + transforms-cap: "Transforms" + dataframe-transform: "transform" + dataframe-transform-cap: "Transform" + dataframe-transforms: "transforms" + dataframe-transforms-cap: "Transforms" + dfanalytics-cap: "Data frame analytics" + dfanalytics: "data frame analytics" + dataframe-analytics-config: "'{dataframe} analytics config'" + dfanalytics-job: "'{dataframe} analytics job'" + dfanalytics-jobs: "'{dataframe} analytics jobs'" + dfanalytics-jobs-cap: "'{dataframe-cap} analytics jobs'" + cdataframe: "continuous data frame" + cdataframes: "continuous data frames" + cdataframe-cap: "Continuous data frame" + cdataframes-cap: "Continuous data frames" + cdataframe-transform: "continuous transform" + cdataframe-transforms: "continuous transforms" + cdataframe-transforms-cap: "Continuous transforms" + ctransform: "continuous transform" + ctransform-cap: "Continuous transform" + ctransforms: "continuous transforms" + ctransforms-cap: "Continuous transforms" + oldetection: "outlier detection" + oldetection-cap: "Outlier detection" + olscore: "outlier score" + olscores: "outlier scores" + fiscore: "feature influence score" + evaluatedf-api: "evaluate {dataframe} analytics API" + evaluatedf-api-cap: "Evaluate {dataframe} analytics API" + binarysc: "binary soft classification" + binarysc-cap: "Binary soft classification" + regression: "regression" + regression-cap: "Regression" + reganalysis: "regression analysis" + reganalysis-cap: "Regression analysis" + depvar: "dependent variable" + feature-var: "feature variable" + feature-vars: "feature variables" + feature-vars-cap: "Feature variables" + classification: "classification" + classification-cap: "Classification" + classanalysis: "classification analysis" + classanalysis-cap: "Classification analysis" + infer-cap: "Inference" + infer: "inference" + lang-ident-cap: "Language identification" + lang-ident: "language identification" + data-viz: "Data Visualizer" + file-data-viz: "File Data Visualizer" + feat-imp: "feature importance" + feat-imp-cap: "Feature importance" + nlp: "natural language processing" + nlp-cap: "Natural language processing" + apm-agent: "APM agent" + apm-go-agent: "Elastic APM Go agent" + apm-go-agents: "Elastic APM Go agents" + apm-ios-agent: "Elastic APM iOS agent" + apm-ios-agents: "Elastic APM iOS agents" + apm-java-agent: "Elastic APM Java agent" + apm-java-agents: "Elastic APM Java agents" + apm-dotnet-agent: "Elastic APM .NET agent" + apm-dotnet-agents: "Elastic APM .NET agents" + apm-node-agent: "Elastic APM Node.js agent" + apm-node-agents: "Elastic APM Node.js agents" + apm-php-agent: "Elastic APM PHP agent" + apm-php-agents: "Elastic APM PHP agents" + apm-py-agent: "Elastic APM Python agent" + apm-py-agents: "Elastic APM Python agents" + apm-ruby-agent: "Elastic APM Ruby agent" + apm-ruby-agents: "Elastic APM Ruby agents" + apm-rum-agent: "Elastic APM Real User Monitoring (RUM) JavaScript agent" + apm-rum-agents: "Elastic APM RUM JavaScript agents" + apm-lambda-ext: "Elastic APM AWS Lambda extension" + project-monitors: "project monitors" + project-monitors-cap: "Project monitors" + private-location: "Private Location" + private-locations: "Private Locations" + pwd: "YOUR_PASSWORD" + esh: "ES-Hadoop" + default-dist: "default distribution" + oss-dist: "OSS-only distribution" + observability: "Observability" + api-request-title: "Request" + api-prereq-title: "Prerequisites" + api-description-title: "Description" + api-path-parms-title: "Path parameters" + api-query-parms-title: "Query parameters" + api-request-body-title: "Request body" + api-response-codes-title: "Response codes" + api-response-body-title: "Response body" + api-example-title: "Example" + api-examples-title: "Examples" + api-definitions-title: "Properties" + multi-arg: "†footnoteref:[multi-arg,This parameter accepts multiple arguments.]" + multi-arg-ref: "†footnoteref:[multi-arg]" + yes-icon: "image:https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png[Yes,20,15]" + no-icon: "image:https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png[No,20,15]" + es-repo: "https://github.com/elastic/elasticsearch/" + es-issue: "https://github.com/elastic/elasticsearch/issues/" + es-pull: "https://github.com/elastic/elasticsearch/pull/" + es-commit: "https://github.com/elastic/elasticsearch/commit/" + kib-repo: "https://github.com/elastic/kibana/" + kib-issue: "https://github.com/elastic/kibana/issues/" + kibana-issue: "'{kib-repo}issues/'" + kib-pull: "https://github.com/elastic/kibana/pull/" + kibana-pull: "'{kib-repo}pull/'" + kib-commit: "https://github.com/elastic/kibana/commit/" + ml-repo: "https://github.com/elastic/ml-cpp/" + ml-issue: "https://github.com/elastic/ml-cpp/issues/" + ml-pull: "https://github.com/elastic/ml-cpp/pull/" + ml-commit: "https://github.com/elastic/ml-cpp/commit/" + apm-repo: "https://github.com/elastic/apm-server/" + apm-issue: "https://github.com/elastic/apm-server/issues/" + apm-pull: "https://github.com/elastic/apm-server/pull/" + kibana-blob: "https://github.com/elastic/kibana/blob/current/" + apm-get-started-ref: "https://www.elastic.co/guide/en/apm/get-started/current" + apm-server-ref: "https://www.elastic.co/guide/en/apm/server/current" + apm-server-ref-v: "https://www.elastic.co/guide/en/apm/server/current" + apm-server-ref-m: "https://www.elastic.co/guide/en/apm/server/master" + apm-server-ref-62: "https://www.elastic.co/guide/en/apm/server/6.2" + apm-server-ref-64: "https://www.elastic.co/guide/en/apm/server/6.4" + apm-server-ref-70: "https://www.elastic.co/guide/en/apm/server/7.0" + apm-overview-ref-v: "https://www.elastic.co/guide/en/apm/get-started/current" + apm-overview-ref-70: "https://www.elastic.co/guide/en/apm/get-started/7.0" + apm-overview-ref-m: "https://www.elastic.co/guide/en/apm/get-started/master" + infra-guide: "https://www.elastic.co/guide/en/infrastructure/guide/current" + a-data-source: "a data view" + icon-bug: "pass:[]" + icon-checkInCircleFilled: "pass:[]" + icon-warningFilled: "pass:[]" diff --git a/docs/images/azure-functions-configuration.png b/docs/images/azure-functions-configuration.png new file mode 100644 index 000000000..751b51870 Binary files /dev/null and b/docs/images/azure-functions-configuration.png differ diff --git a/docs/images/dynamic-config.svg b/docs/images/dynamic-config.svg new file mode 100644 index 000000000..df62a3c84 --- /dev/null +++ b/docs/images/dynamic-config.svg @@ -0,0 +1 @@ + DynamicDynamic \ No newline at end of file diff --git a/docs/images/unblock-profiler-dll.png b/docs/images/unblock-profiler-dll.png new file mode 100644 index 000000000..6ff52bbe0 Binary files /dev/null and b/docs/images/unblock-profiler-dll.png differ diff --git a/docs/reference/config-all-options-summary.md b/docs/reference/config-all-options-summary.md new file mode 100644 index 000000000..f528ffafe --- /dev/null +++ b/docs/reference/config-all-options-summary.md @@ -0,0 +1,54 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/config-all-options-summary.html +--- + +# All options summary [config-all-options-summary] + +| Option name | [![dynamic config](../images/dynamic-config.svg "") ](/reference/configuration.md#dynamic-configuration) | Keywords | +| --- | --- | --- | +| [`ApiKey`](/reference/config-reporter.md#config-api-key) | No | Reporter | +| [`ApplicationNamespaces`](/reference/config-stacktrace.md#config-application-namespaces) | No | Stacktrace | +| [`CaptureBody`](/reference/config-http.md#config-capture-body) | Yes | HTTP, Performance | +| [`CaptureBodyContentTypes`](/reference/config-http.md#config-capture-body-content-types) | Yes | HTTP, Performance | +| [`CaptureHeaders`](/reference/config-http.md#config-capture-headers) | Yes | HTTP, Performance | +| [`CentralConfig`](/reference/config-core.md#config-central-config) | No | Core | +| [`CloudProvider`](/reference/config-reporter.md#config-cloud-provider) | No | Reporter | +| [`DisableMetrics`](/reference/config-reporter.md#config-disable-metrics) | No | Reporter | +| [`Enabled`](/reference/config-core.md#config-enabled) | No | Core | +| [`OpentelemetryBridgeEnabled`](/reference/config-core.md#config-opentelemetry-bridge-enabled) | No | Core | +| [`Environment`](/reference/config-core.md#config-environment) | No | Core | +| [`ExcludedNamespaces`](/reference/config-stacktrace.md#config-excluded-namespaces) | No | Stacktrace | +| [`ExitSpanMinDuration`](/reference/config-core.md#config-exit-span-min-duration) | Yes | Core, Performance | +| [`FlushInterval`](/reference/config-reporter.md#config-flush-interval) | No | Reporter | +| [`GlobalLabels`](/reference/config-core.md#config-global-labels) | No | Core | +| [`IgnoreMessageQueues`](/reference/config-messaging.md#config-ignore-message-queues) | Yes | Messaging, Performance | +| [`HostName`](/reference/config-core.md#config-hostname) | No | Core | +| [`LogLevel`](/reference/config-supportability.md#config-log-level) | Yes | Supportability | +| [`MaxBatchEventCount`](/reference/config-reporter.md#config-max-batch-event-count) | No | Reporter | +| [`MaxQueueEventCount`](/reference/config-reporter.md#config-max-queue-event-count) | No | Reporter | +| [`MetricsInterval`](/reference/config-reporter.md#config-metrics-interval) | No | Reporter | +| [`Recording`](/reference/config-core.md#config-recording) | Yes | Core | +| [`SanitizeFieldNames`](/reference/config-core.md#config-sanitize-field-names) | Yes | Core | +| [`SecretToken`](/reference/config-reporter.md#config-secret-token) | No | Reporter | +| [`ServerCert`](/reference/config-reporter.md#config-server-cert) | No | Reporter | +| [`ServerUrl`](/reference/config-reporter.md#config-server-url) | No | Reporter | +| [`ServiceName`](/reference/config-core.md#config-service-name) | No | Core | +| [`ServiceNodeName`](/reference/config-core.md#config-service-node-name) | No | Core | +| [`ServiceVersion`](/reference/config-core.md#config-service-version) | No | Core | +| [`SpanCompressionEnabled`](/reference/config-core.md#config-span-compression-enabled) | Yes | Core, Performance | +| [`SpanCompressionExactMatchMaxDuration`](/reference/config-core.md#config-span-compression-exact-match-max-duration) | Yes | Core, Performance | +| [`SpanCompressionSameKindMaxDuration`](/reference/config-core.md#config-span-compression-same-kind-max-duration) | Yes | Core, Performance | +| [`SpanStackTraceMinDuration`](/reference/config-stacktrace.md#config-span-stack-trace-min-duration) | Yes | Stacktrace, Performance | +| [`StackTraceLimit`](/reference/config-stacktrace.md#config-stack-trace-limit) | Yes | Stacktrace, Performance | +| [`TraceContextIgnoreSampledFalse`](/reference/config-http.md#config-trace-context-ignore-sampled-false) | No | Core | +| [`TransactionIgnoreUrls`](/reference/config-http.md#config-transaction-ignore-urls) | Yes | HTTP, Performance | +| [`TransactionNameGroups`](/reference/config-http.md#config-transaction-name-groups) | Yes | HTTP | +| [`TransactionMaxSpans`](/reference/config-core.md#config-transaction-max-spans) | Yes | Core, Performance | +| [`TransactionSampleRate`](/reference/config-core.md#config-transaction-sample-rate) | Yes | Core, Performance | +| [`TraceContinuationStrategy`](/reference/config-http.md#config-trace-continuation-strategy) | Yes | HTTP, Performance | +| [`UseElasticTraceparentHeader`](/reference/config-http.md#config-use-elastic-apm-traceparent-header) | No | HTTP | +| [`UsePathAsTransactionName`](/reference/config-http.md#config-use-path-as-transaction-name) | Yes | HTTP | +| [`UseWindowsCredentials`](/reference/config-http.md#config-use-windows-credentials) | No | Reporter | +| [`VerifyServerCert`](/reference/config-reporter.md#config-verify-server-cert) | No | Reporter | + diff --git a/docs/reference/config-core.md b/docs/reference/config-core.md new file mode 100644 index 000000000..bb68b667c --- /dev/null +++ b/docs/reference/config-core.md @@ -0,0 +1,315 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/config-core.html +--- + +# Core configuration options [config-core] + + +## `Recording` ([1.7.0]) [config-recording] + +[![dynamic config](../images/dynamic-config.svg "") ](/reference/configuration.md#dynamic-configuration) + +A Boolean specifying if the agent should be recording or not. When recording, the agent captures HTTP requests, tracks errors, and collects and sends metrics. When not recording, the agent works as a noop, where it does not collect data or communicate with the APM server, except for polling the central configuration endpoint. This is a reversible switch, so the agent threads are not killed when deactivated, but they will be mostly idle in this state, so the overhead should be negligible. + +Use this setting to dynamically disable Elastic APM at runtime. + +::::{warning} +Setting `Recording` to `false` influences the behavior of the [*Public API*](/reference/public-api.md). When the agent is not active, it won’t keep track of transactions, spans, and any related properties. +:::: + + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_RECORDING` | `ElasticApm:Recording` | + +| Default | Type | +| --- | --- | +| `true` | Boolean | + + +## `Enabled` ([1.7.0]) [config-enabled] + +Setting this to `false` will completely disable the agent, including instrumentation and remote config polling. If you want to dynamically change the status of the agent, use [`recording`](#config-recording) instead. + +::::{warning} +Setting `Enabled` to `false` influences the behavior of the [*Public API*](/reference/public-api.md). When the agent is not active, it won’t keep track of transactions, spans, and any related properties. +:::: + + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_ENABLED` | `ElasticApm:Enabled` | + +| Default | Type | +| --- | --- | +| `true` | Boolean | + + +## `ServiceName` [config-service-name] + +This is used to keep all the errors and transactions of your service together and is the primary filter in the Elastic APM user interface. + +::::{note} +The service name must conform to this regular expression: `^[a-zA-Z0-9 _-]+$`. In other words, your service name must only contain characters from the ASCII alphabet, numbers, dashes, underscores, and spaces. Characters in service names that don’t match the regular expression will be replaced with the `_` symbol. +:::: + + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_SERVICE_NAME` | `ElasticApm:ServiceName` | + +| Default | Type | +| --- | --- | +| Name of the entry assembly | String | + + +## `ServiceNodeName` ([1.3]) [config-service-node-name] + +This is an optional name used to differentiate between nodes in a service. If this is not set, data aggregations are done based on a container ID (where valid) or on the reported hostname (automatically discovered). + +::::{note} +This feature requires APM Server versions >= 7.5 +:::: + + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_SERVICE_NODE_NAME` | `ElasticApm:ServiceNodeName` | + +| Default | Type | +| --- | --- | +| `` | String | + + +## `ServiceVersion` [config-service-version] + +A version string for the currently deployed version of the service. If you don’t version your deployments, the recommended value for this field is the commit identifier of the deployed revision, e.g. the output of `git rev-parse HEAD`. + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_SERVICE_VERSION` | `ElasticApm:ServiceVersion` | + +| Default | Type | +| --- | --- | +| Informational version of the entry assembly | String | + + +## `HostName` ([1.7]) [config-hostname] + +This allows for the reported hostname to be manually specified. If this is not set, the hostname will be looked up. + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_HOSTNAME` | `ElasticApm:HostName` | + +| Default | Type | +| --- | --- | +| `` | String | + + +## `Environment` ([1.1]) [config-environment] + +The name of the environment that this service is deployed in, e.g. "production" or "staging". + +Environments allow you to easily filter data on a global level in the APM app. It’s important to be consistent when naming environments across agents. See [environment selector](docs-content://solutions/observability/apps/filter-application-data.md#apm-filter-your-data-service-environment-filter) in the Kibana UI for more information. + +::::{note} +This feature is fully supported in the APM app in Kibana versions >= 7.2. You must use the query bar to filter for a specific environment in versions prior to 7.2. +:::: + + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_ENVIRONMENT` | `ElasticApm:Environment` | + +| Default | Type | +| --- | --- | +| See note below | String | + +::::{note} +On ASP.NET Core application the agent uses [EnvironmentName from IHostingEnvironment](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.hosting.ihostingenvironment.environmentname?view=aspnetcore-2.2#Microsoft_AspNetCore_Hosting_IHostingEnvironment_EnvironmentName) as default environment name. +:::: + + + +## `TransactionSampleRate` [config-transaction-sample-rate] + +[![dynamic config](../images/dynamic-config.svg "") ](/reference/configuration.md#dynamic-configuration) + +By default, the agent samples every transaction (e.g. a request to your service). To reduce overhead and storage requirements, set the sample rate to a value between 0.0 and 1.0. The agent will still record the overall time and result for unsampled transactions, but no context information, labels, or spans will be recorded. + +::::{note} +When parsing the value for this option, the agent doesn’t consider the current culture. It also expects that a period (`.`) is used to separate the integer and the fraction of a floating-point number. +:::: + + +This setting can be changed after the agent starts. + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_TRANSACTION_SAMPLE_RATE` | `ElasticApm:TransactionSampleRate` | + +| Default | Type | +| --- | --- | +| 1.0 | Double | + + +## `TransactionMaxSpans` (performance) ([1.1.1]) [config-transaction-max-spans] + +[![dynamic config](../images/dynamic-config.svg "") ](/reference/configuration.md#dynamic-configuration) + +This limits the amount of spans that are recorded per transaction. This is helpful when a transaction creates a very high amount of spans, for example, thousands of SQL queries. Setting an upper limit helps prevent overloading the Agent and APM server in these edge cases. + +::::{note} +A value of `0` means that spans will never be collected. Setting `-1` means that spans will never be dropped. The Agent will revert to the default value if the value is set below `-1`. +:::: + + +This setting can be changed after agent starts. + +| Environment variable name | IConfiguration key | +| --- | --- | +| `ELASTIC_APM_TRANSACTION_MAX_SPANS` | `ElasticApm:TransactionMaxSpans` | + +| Default | Type | +| --- | --- | +| `500` | Integer | + + +## `CentralConfig` ([1.1]) [config-central-config] + +If set to `true`, the agent makes periodic requests to the APM Server to fetch the latest [APM Agent configuration](docs-content://solutions/observability/apps/apm-agent-central-configuration.md). + +| Environment variable name | IConfiguration key | +| --- | --- | +| `ELASTIC_APM_CENTRAL_CONFIG` | `ElasticApm:CentralConfig` | + +| Default | Type | +| --- | --- | +| true | Boolean | + + +## `SanitizeFieldNames` ([1.2]) [config-sanitize-field-names] + +[![dynamic config](../images/dynamic-config.svg "") ](/reference/configuration.md#dynamic-configuration) + +Sometimes, sanitizing, i.e., redacting sensitive data sent to Elastic APM, is necessary. This configuration accepts a comma-separated list of wildcard patterns of field names that should be sanitized. These apply to HTTP headers for requests and responses, cookies and `application/x-www-form-urlencoded` data. + +::::{important} +This setting only applies to values captured automatically by the agent. If you capture the request body manually with the public API, this configuration doesn’t apply, and the agent won’t sanitize the body. +:::: + + +The wildcard, `*`, matches zero or more characters, and matching is case insensitive by default. Prepending an element with `(?-i)` makes the matching case sensitive. Examples: `/foo/*/bar/*/baz*`, `*foo*`. + +Please review the data captured by Elastic APM carefully to ensure it does not contain sensitive information. If you find sensitive data in your {{es}} index, add an additional entry to this list. Setting a value here will **overwrite** the defaults, so be sure to include the default entries as well. + +::::{note} +Sensitive information should not be sent in the query string. Data in the query string is considered non-sensitive. See [owasp.org](https://www.owasp.org/index.php/Information_exposure_through_query_strings_in_url) for more information. +:::: + + +**`Cookie` header sanitization:** + +The `Cookie` header is automatically redacted for incoming HTTP request transactions. Each name-value pair from the cookie list is parsed by the agent and sanitized based on the `SanitizeFieldNames` configuration. Cookies with sensitive data in their value can be redacted by adding the cookie’s name to the comma-separated list. + +| Environment variable name | IConfiguration key | +| --- | --- | +| `ELASTIC_APM_SANITIZE_FIELD_NAMES` | `ElasticApm:SanitizeFieldNames` | + +| Default | Type | +| --- | --- | +| `password, passwd, pwd, secret, *key, *token*, *session*, *credit*, *card*, *auth*, set-cookie, *principal*` | Comma separated string | + + +## `GlobalLabels` ([1.2]) [config-global-labels] + +Labels are added to all events with the format `key=value[,key=value[,...]]`. Any labels set by the application via the agent’s public API will override global labels with the same keys. + +| Environment variable name | IConfiguration key | +| --- | --- | +| `ELASTIC_APM_GLOBAL_LABELS` | `ElasticApm:GlobalLabels` | + +| Default | Type | +| --- | --- | +| | Map of string to string | + +::::{note} +This option requires APM Server 7.2 or later. It will have no effect on older versions. +:::: + + + +## `SpanCompressionEnabled` ([1.14]) [config-span-compression-enabled] + +[![dynamic config](../images/dynamic-config.svg "") ](/reference/configuration.md#dynamic-configuration) + +Setting this option to true will enable span compression feature. Span compression reduces the collection, processing, and storage overhead, and removes clutter from the UI. The tradeoff is that some information such as DB statements of all the compressed spans will not be collected. + +| Environment variable name | IConfiguration key | +| --- | --- | +| `ELASTIC_APM_SPAN_COMPRESSION_ENABLED` | `ElasticApm:SpanCompressionEnabled` | + +| Default | Type | +| --- | --- | +| `true` | Boolean | + + +## `SpanCompressionExactMatchMaxDuration` ([1.14]) [config-span-compression-exact-match-max-duration] + +[![dynamic config](../images/dynamic-config.svg "") ](/reference/configuration.md#dynamic-configuration) + +Consecutive spans that are exact match and that are under this threshold will be compressed into a single composite span. This option does not apply to composite spans. This reduces the collection, processing, and storage overhead, and removes clutter from the UI. The tradeoff is that the DB statements of all the compressed spans will not be collected. + +| Environment variable name | IConfiguration key | +| --- | --- | +| `ELASTIC_APM_SPAN_COMPRESSION_EXACT_MATCH_MAX_DURATION` | `ElasticApm:SpanCompressionExactMatchMaxDuration` | + +| Default | Type | +| --- | --- | +| `50ms` | TimeDuration | + + +## `SpanCompressionSameKindMaxDuration` ([1.14]) [config-span-compression-same-kind-max-duration] + +[![dynamic config](../images/dynamic-config.svg "") ](/reference/configuration.md#dynamic-configuration) + +Consecutive spans to the same destination that are under this threshold will be compressed into a single composite span. This option does not apply to composite spans. This reduces the collection, processing, and storage overhead, and removes clutter from the UI. The tradeoff is that the DB statements of all the compressed spans will not be collected. + +| Environment variable name | IConfiguration key | +| --- | --- | +| `ELASTIC_APM_SPAN_COMPRESSION_SAME_KIND_MAX_DURATION` | `ElasticApm:SpanCompressionSameKindMaxDuration` | + +| Default | Type | +| --- | --- | +| `0ms` | TimeDuration | + + +## `ExitSpanMinDuration` ([1.14]) [config-exit-span-min-duration] + +[![dynamic config](../images/dynamic-config.svg "") ](/reference/configuration.md#dynamic-configuration) + +Sets the minimum duration of exit spans. Exit spans with a duration lesser than this threshold are attempted to be discarded. If the exit span is equal or greater the threshold, it should be kept. In some cases exit spans cannot be discarded. For example, spans that propagate the trace context to downstream services, such as outgoing HTTP requests, can’t be discarded. However, external calls that don’t propagate context, such as calls to a database, can be discarded using this threshold. Additionally, spans that lead to an error can’t be discarded. + +| Environment variable name | IConfiguration key | +| --- | --- | +| `ELASTIC_APM_EXIT_SPAN_MIN_DURATION` | `ElasticApm:ExitSpanMinDuration` | + +| Default | Type | +| --- | --- | +| `0ms` | TimeDuration | + + +## `OpentelemetryBridgeEnabled` ([1.13]) [config-opentelemetry-bridge-enabled] + +Setting this option to `false` will disable the [OpenTelemetry Bridge](/reference/opentelemetry-bridge.md). This will disable the use of the vendor-neutral OpenTelemetry Tracing API (the [Activity API](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.activity?view=net-5.0) in .NET) to manually instrument your code, and have the Elastic .NET APM agent handle those API calls. + +| Environment variable name | IConfiguration key | +| --- | --- | +| `ELASTIC_APM_OPENTELEMETRY_BRIDGE_ENABLED` | `ElasticApm:OpentelemetryBridgeEnabled` | + +| Default | Type | +| --- | --- | +| `true` | Boolean | + diff --git a/docs/reference/config-http.md b/docs/reference/config-http.md new file mode 100644 index 000000000..bbc9e7fc3 --- /dev/null +++ b/docs/reference/config-http.md @@ -0,0 +1,259 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/config-http.html +--- + +# HTTP configuration options [config-http] + + +## `CaptureBody` (performance) ([1.0.1]) [config-capture-body] + +[![dynamic config](../images/dynamic-config.svg "") ](/reference/configuration.md#dynamic-configuration) + +For transactions that are HTTP requests, the agent can optionally capture the request body, e.g., POST variables. If the request has a body and this setting is disabled, the body will be shown as [REDACTED]. This option is case-insensitive. + +::::{important} +To allow capturing request bodies, the agent sets `AllowSynchronousIO` to `true` on a per request basis in ASP.NET Core, since capturing can occur in synchronous code paths. + +[With ASP.NET Core 3.0 onwards, `AllowSynchronousIO` is `false` by default](https://docs.microsoft.com/en-us/aspnet/core/migration/22-to-30?#allowsynchronousio-disabled) because a large number of blocking synchronous I/O operations can lead to thread pool starvation, which makes the application unresponsive. If your application becomes unresponsive with this feature enabled, consider disabling capturing. + +In ASP.NET (.NET Full Framework), this setting has no effect on non-buffered requests (see [HttpRequest.ReadEntityBodyMode](https://docs.microsoft.com/en-us/dotnet/api/system.web.httprequest.readentitybodymode?view=netframework-4.8)). + +:::: + + +::::{warning} +Request bodies often contain sensitive values like passwords and credit card numbers. If your service handles data like this, we advise to only enable this feature with care. Turning on body capturing can also significantly increase the overhead in terms of heap usage, network utilization, and Elasticsearch index size. + +:::: + + +Possible options are `off`, `errors`, `transactions` and `all`: + +* `off` - request bodies will never be reported +* `errors` - request bodies will only be reported with errors +* `transactions` - request bodies will only be reported with request transactions +* `all` - request bodies will be reported with both errors and request transactions + +This setting can be changed after the agent starts. + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_CAPTURE_BODY` | `ElasticApm:CaptureBody` | + +| Default | Type | +| --- | --- | +| `off` | String | + + +## `CaptureBodyContentTypes` (performance) ([1.0.1]) [config-capture-body-content-types] + +Configures the content types to be captured. + +This option supports the wildcard `*`, which matches zero or more characters. Examples: `/foo/*/bar/*/baz*`, `*foo*`. Matching is case insensitive. + +This setting can be changed after the agent starts. + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_CAPTURE_BODY_CONTENT_TYPES` | `ElasticApm:CaptureBodyContentTypes` | + +| Default | Type | +| --- | --- | +| `application/x-www-form-urlencoded*, text/*, application/json*, application/xml*` | Comma separated string | + + +## `CaptureHeaders` (performance) [config-capture-headers] + +[![dynamic config](../images/dynamic-config.svg "") ](/reference/configuration.md#dynamic-configuration) + +If set to `true`, the agent will capture request and response headers, including cookies. + +::::{note} +Setting this to `false` reduces memory allocations, network bandwidth, and disk space used by {{es}}. +:::: + + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_CAPTURE_HEADERS` | `ElasticApm:CaptureHeaders` | + +| Default | Type | +| --- | --- | +| `true` | Boolean | + + +## `TraceContinuationStrategy` (performance) ([1.17.0]) [config-trace-continuation-strategy] + +[![dynamic config](../images/dynamic-config.svg "") ](/reference/configuration.md#dynamic-configuration) + +Valid options: `continue`, `restart`, `restart_external`. + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_TRACE_CONTINUATION_STRATEGY` | `ElasticApm:TraceContinuationStrategy` | + +| Default | Type | +| --- | --- | +| `continue` | String | + +The `traceparent` header of requests that are traced by the Elastic APM .NET Agent might have been added by a 3rd party component. + +This situation becomes more and more common as the w3c trace context gets adopted. In such cases you may end up with traces where part of the trace is outside of Elastic APM. + +In order to handle this properly, the agent offers trace continuation strategies with the following values and behavior: + +* `continue`: The agent takes the `traceparent` header as it is and applies it to the new transaction. +* `restart`: The agent always creates a new trace with a new trace id. In this case the agent creates a span link in the new transaction pointing to the original `traceparent`. +* `restart_external`: The agent first checks the `tracestate` header. If the header contains the `es` vendor flag (which means the request is coming from a service monitored by an Elastic APM Agent), it’s treated as internal, otherwise (including the case when the `tracestate` header is not present) it’s treated as external. In case of external calls the agent creates a new trace with a new trace id and creates a link in the new transaction pointing to the original trace. + + +## `TransactionIgnoreUrls` (performance) [config-transaction-ignore-urls] + +[![dynamic config](../images/dynamic-config.svg "") ](/reference/configuration.md#dynamic-configuration) + +This is used to restrict requests to certain URLs from being instrumented. + +This property should be set to a comma separated string containing one or more paths. + +For example, in order to ignore the URLs `/foo` and `/bar`, set the configuration value to `"/foo,/bar"`. + +When an incoming HTTP request is detected, its request path will be tested against each element in this list. For example, adding `/home/index` to this list would match and remove instrumentation from the following URLs: + +```txt +https://www.mycoolsite.com/home/index +http://localhost/home/index +http://whatever.com/home/index?value1=123 +``` + +In other words, the matching always happens based on the request path—hosts and query strings are ignored. + +This option supports the wildcard `*`, which matches zero or more characters. Examples: `"/foo/*/bar/*/baz*`, `*foo*"`. Matching is case insensitive by default. Prepending an element with `(?-i)` makes the matching case sensitive. + +::::{note} +All errors that are captured during a request to an ignored URL are still sent to the APM Server regardless of this setting. +:::: + + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_TRANSACTION_IGNORE_URLS` | `ElasticApm:TransactionIgnoreUrls` | + +| Default | Type | +| --- | --- | +| `/VAADIN/*, /heartbeat*, /favicon.ico, *.js, *.css, *.jpg, *.jpeg, *.png, *.gif, *.webp, *.svg, *.woff, *.woff2` | Comma separated string | + +::::{note} +Changing this configuration will overwrite the default value. +:::: + + + +## `TransactionNameGroups` ([1.27.0]) [config-transaction-name-groups] + +[![dynamic config](../images/dynamic-config.svg "") ](/reference/configuration.md#dynamic-configuration) + +With this option, you can group transaction names that contain dynamic parts with a wildcard expression. For example, the pattern `GET /user/*/cart` would consolidate transactions, such as `GET /users/42/cart` and `GET /users/73/cart` into a single transaction name `GET /users/*/cart`, hence reducing the transaction name cardinality. + +This option supports the wildcard `*`, which matches zero or more characters. Examples: `GET /foo/*/bar/*/baz*``, `*foo*`. Matching is case insensitive by default. Prepending an element with (?-i) makes the matching case sensitive. + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_TRANSACTION_NAME_GROUPS` | `ElasticApm:TransactionNameGroups` | + +| Default | Type | +| --- | --- | +| `` | String | + + +## `UseElasticTraceparentHeader` ([1.3.0]) [config-use-elastic-apm-traceparent-header] + +To enable [distributed tracing](docs-content://solutions/observability/apps/traces.md), the agent adds trace context headers to outgoing HTTP requests made with the `HttpClient` type. These headers (`traceparent` and `tracestate`) are defined in the [W3C Trace Context](https://www.w3.org/TR/trace-context-1/) specification. + +When this setting is `true`, the agent also adds the header `elasticapm-traceparent` for backwards compatibility with older versions of Elastic APM agents. Versions prior to `1.3.0` only read the `elasticapm-traceparent` header. + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_USE_ELASTIC_TRACEPARENT_HEADER` | `ElasticApm:UseElasticTraceparentHeader` | + +| Default | Type | +| --- | --- | +| `true` | Boolean | + + +## `UsePathAsTransactionName` ([1.27.0]) [config-use-path-as-transaction-name] + +[![dynamic config](../images/dynamic-config.svg "") ](/reference/configuration.md#dynamic-configuration) + +If set to `true`, transaction names of unsupported or partially-supported frameworks will be in the form of `$method $path` instead of just `$method unknown route`. + +::::{warning} +If your URLs contain path parameters like `/user/$userId`, you should be very careful when enabling this flag, as it can lead to an explosion of transaction groups. Take a look at the [`TransactionNameGroups`](#config-transaction-name-groups) option on how to mitigate this problem by grouping URLs together. +:::: + + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_USE_PATH_AS_TRANSACTION_NAME` | `ElasticApm:UsePathAsTransactionName` | + +| Default | Type | +| --- | --- | +| `true` | Boolean | + + +## `UseWindowsCredentials` [config-use-windows-credentials] + +Set this property to true when requests made by the APM agent should, if requested by the server, be authenticated using the credentials of the currently logged on user. + +This is useful when using windows authentication on a proxy, that routes APM agent requests to the APM server. + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_USE_WINDOWS_CREDENTIALS` | `ElasticApm:UseWindowsCredentials` | + +| Default | Type | +| --- | --- | +| `false` | Boolean | + + +## `BaggageToAttach` ([1.24]) [config-baggage-to-attach] + +[![dynamic config](../images/dynamic-config.svg "") ](/reference/configuration.md#dynamic-configuration) + +Controls which baggage values are automatically attached to the given event (transaction, span, error). Baggage values are derived from the `baggage` header defined in the [W3C Baggage specification](https://www.w3.org/TR/baggage/). You can programmatically write and read baggage values via the [Activity API](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.activity?view=net-6.0). For more details, see [`our documentation on how to integrate with OpenTelemetry`](/reference/opentelemetry-bridge.md#baggage-api). + +| Environment variable name | IConfiguration key | +| --- | --- | +| `ELASTIC_APM_BAGGAGE_TO_ATTACH` | `ElasticApm:BaggageToAttach` | + +| Default | Type | +| --- | --- | +| `*` | Comma separated string | + + +## `TraceContextIgnoreSampledFalse` [config-trace-context-ignore-sampled-false] + +::::{important} +Use of `TraceContextIgnoreSampledFalse` is deprecated. Use `TraceContinuationStrategy` with the `restart_external` value. +:::: + + +The agent uses the [W3C Trace Context](https://www.w3.org/TR/trace-context/) specification and standards for distributed tracing. The traceparent header from the W3C Trace Context specification defines a [sampled flag](https://www.w3.org/TR/trace-context/#sampled-flag) which is propagated from a caller service to a callee service, and determines whether a trace is sampled in the callee service. The default behavior of the agent honors the sampled flag value and behaves accordingly. + +There may be cases where you wish to change the default behavior of the agent with respect to the sampled flag. By setting the `TraceContextIgnoreSampled` configuration value to `true`, the agent ignores the sampled flag of the W3C Trace Context traceparent header when it has a value of `false` **and** and there is no agent specific tracestate header value present. In ignoring the sampled flag, the agent makes a sampling decision based on the [sample rate](/reference/config-core.md#config-transaction-sample-rate). This can be useful when a caller service always sets a sampled flag value of `false`, that results in the agent never sampling any transactions. + +::::{important} +.NET 5 applications set the W3C Trace Context for outgoing HTTP requests by default, but with the traceparent header sampled flag set to `false`. If a .NET 5 application has an active agent, the agent ensures that the sampled flag is propagated with the agent’s sampling decision. If a .NET 5 application does not have an active agent however, and the application calls another service that does have an active agent, the propagation of a sampled flag value of `false` results in no sampled transactions in the callee service. + +If your application is called by an .NET 5 application that does not have an active agent, setting the `TraceContextIgnoreSampledFalse` configuration value to `true` instructs the agent to start a new transaction and make a sampling decision based on the [sample rate](/reference/config-core.md#config-transaction-sample-rate), when the traceparent header sampled flag has a value of `false` **and** there is no agent specific tracestate header value present. + +:::: + + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_TRACE_CONTEXT_IGNORE_SAMPLED_FALSE` | `ElasticApm:TraceContextIgnoreSampledFalse` | + +| Default | Type | +| --- | --- | +| `false` | Boolean | diff --git a/docs/reference/config-messaging.md b/docs/reference/config-messaging.md new file mode 100644 index 000000000..163210b41 --- /dev/null +++ b/docs/reference/config-messaging.md @@ -0,0 +1,24 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/config-messaging.html +--- + +# Messaging configuration options [config-messaging] + + +## `IgnoreMessageQueues` ([1.10]) [config-ignore-message-queues] + +Used to filter out specific messaging queues/topics/exchanges from being traced. When set, sends-to and receives-from the specified queues/topics/exchanges will be ignored. + +This config accepts a comma separated string of wildcard patterns of queues/topics/exchange names which should be ignored. + +The wildcard, `*`, matches zero or more characters, and matching is case insensitive by default. Prepending an element with `(?-i)` makes the matching case sensitive. Examples: `/foo/*/bar/*/baz*`, `*foo*`. + +| Default | Type | +| --- | --- | +| | String | + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_IGNORE_MESSAGE_QUEUES` | `ElasticApm:IgnoreMessageQueues` | + diff --git a/docs/reference/config-reporter.md b/docs/reference/config-reporter.md new file mode 100644 index 000000000..f1b7250ed --- /dev/null +++ b/docs/reference/config-reporter.md @@ -0,0 +1,206 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/config-reporter.html +--- + +# Reporter configuration options [config-reporter] + + +## `ServerUrl` [config-server-url] + +The URL for your APM Server. The URL must be fully qualified, including protocol (`http` or `https`) and port. + +::::{important} +Use of `ServerUrls` is deprecated. Use `ServerUrl`. +:::: + + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_SERVER_URL` | `ElasticApm:ServerUrl` | + +| Default | Type | +| --- | --- | +| `http://localhost:8200` | String | + + +## `SecretToken` [config-secret-token] + +A string used to ensure that only your agents can send data to your APM server. + +Both the agents and the APM server have to be configured with the same secret token. Use this setting if the APM Server requires a secret token, for example, when using our hosted {{es}} Service on Elastic Cloud. + +::::{warning} +The `SecretToken` is sent as plain-text in every request to the server, so you should also secure your communications using HTTPS. Unless you do so, your API Key could be observed by an attacker. +:::: + + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_SECRET_TOKEN` | `ElasticApm:SecretToken` | + +| Default | Type | +| --- | --- | +| `` | String | + + +## `ApiKey` ([1.4]) [config-api-key] + +A base64-encoded string used to ensure that only your agents can send data to your APM server. You must have created the API key using the APM server’s [command line tool](docs-content://solutions/observability/apps/api-keys.md). + +::::{note} +This feature is fully supported in the APM Server versions >= 7.6. +:::: + + +::::{warning} +The `APIKey` is sent as plain-text in every request to the server, so you should also secure your communications using HTTPS. Unless you do so, your API Key could be observed by an attacker. +:::: + + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_API_KEY` | `ElasticApm:ApiKey` | + +| Default | Type | +| --- | --- | +| `` | A base64-encoded string | + + +## `VerifyServerCert` ([1.3]) [config-verify-server-cert] + +By default, the agent verifies the SSL certificate if you use an HTTPS connection to the APM server. + +Verification can be disabled by changing this setting to false. + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_VERIFY_SERVER_CERT` | `ElasticApm:VerifyServerCert` | + +| Default | Type | +| --- | --- | +| `true` | Boolean | + +::::{note} +This configuration setting has no effect on .NET Framework versions 4.6.2-4.7.1. We recommend upgrading to .NET Framework 4.7.2 or newer to use this configuration setting. + +:::: + + + +## `ServerCert` ([1.9]) [config-server-cert] + +The path to a PEM-encoded certificate used for SSL/TLS by APM server. Used to perform validation through certificate pinning. + +This can be specified when using a certificate signed by a Certificate Authority (CA) that is not in the trust store, such as a self-signed certificate. + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_SERVER_CERT` | `ElasticApm:ServerCert` | + +| Default | Type | +| --- | --- | +| `` | String | + +::::{note} +This configuration setting has no effect on .NET Framework versions 4.6.2-4.7.1. We recommend upgrading to .NET Framework 4.7.2 or newer to use this configuration setting. + +:::: + + + +## `FlushInterval` ([1.1]) [config-flush-interval] + +The maximal amount of time events are held in the queue until there is enough to send a batch. It’s possible for a batch to contain less than [`MaxBatchEventCount`](#config-max-batch-event-count) events if there are events that need to be sent out because they were held for too long. A lower value will increase the load on your APM server, while a higher value can increase the memory pressure on your app. A higher value also impacts the time until transactions are indexed and searchable in Elasticsearch. + +Supports the duration suffixes `ms`, `s` and `m`. Example: `30s`. The default unit for this option is `s`. + +If `FlushInterval` is set to `0` (or `0s`, `0ms`, etc.) and there’s no event sending operation still in progress, then the Agent won’t hold events in the queue and will send them immediately. + +Setting `FlushInterval` to a negative value (for example `-1`, `-54s`, `-89ms`, etc.) is invalid and in that case agent uses the default value instead. + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_FLUSH_INTERVAL` | `ElasticApm:FlushInterval` | + +| Default | Type | +| --- | --- | +| `10s` | TimeDuration | + + +## `MaxBatchEventCount` ([1.1]) [config-max-batch-event-count] + +The maximum number of events to send in a batch. It’s possible for a batch to contain less then the maximum events if there are events that need to be sent out because they were held for too long (see [`FlushInterval`](#config-flush-interval)). + +Setting `MaxBatchEventCount` to `0` or a negative value is invalid and the Agent will use the default value instead. + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_MAX_BATCH_EVENT_COUNT` | `ElasticApm:MaxBatchEventCount` | + +| Default | Type | +| --- | --- | +| 10 | Integer | + + +## `MaxQueueEventCount` ([1.1]) [config-max-queue-event-count] + +The maximum number of events to hold in the queue as candidates to be sent. If the queue is at its maximum capacity then the agent discards the new events until the queue has free space. + +Setting `MaxQueueEventCount` to `0` or a negative value is invalid and the Agent will use the default value instead. + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_MAX_QUEUE_EVENT_COUNT` | `ElasticApm:MaxQueueEventCount` | + +| Default | Type | +| --- | --- | +| 1000 | Integer | + + +## `MetricsInterval` ([1.0.0-beta1]) [config-metrics-interval] + +The interval at which the agent sends metrics to the APM Server. This must be at least `1s`. Set this to `0s` to deactivate. + +Supports the duration suffixes `ms`, `s` and `m`. Example: `30s`. The default unit for this option is `s`. + +| Default | Type | +| --- | --- | +| `30s` | TimeDuration | + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_METRICS_INTERVAL` | `ElasticApm:MetricsInterval` | + + +## `DisableMetrics` ([1.3.0]) [config-disable-metrics] + +This disables the collection of certain metrics. If the name of a metric matches any of the wildcard expressions, it will not be collected. Example: `foo.*,bar.*` + +You can find the name of the available metrics in [*Metrics*](/reference/metrics.md). + +This option supports the wildcard `*`, which matches zero or more characters. Examples: `/foo/*/bar/*/baz*, *foo*`. Matching is case insensitive by default. Prepending an element with (?-i) makes the matching case sensitive. + +| Default | Type | +| --- | --- | +| | Comma separated string | + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_DISABLE_METRICS` | `ElasticApm:DisableMetrics` | + + +## `CloudProvider` ([1.7.0]) [config-cloud-provider] + +Specify which cloud provider should be assumed for metadata collection. By default, the agent attempts to detect the cloud provider and, if that fails, uses trial and error to collect the metadata. + +Valid options are `"auto"`, `"aws"`, `"gcp"`, `"azure"`, and `"none"`. If this config value is set to `"none"`, no cloud metadata will be collected. If set to any of `"aws"`, `"gcp"`, or `"azure"`, attempts to collect metadata will only be performed from the chosen provider. + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_CLOUD_PROVIDER` | `ElasticApm:CloudProvider` | + +| Default | Type | +| --- | --- | +| `auto` | String | + diff --git a/docs/reference/config-stacktrace.md b/docs/reference/config-stacktrace.md new file mode 100644 index 000000000..2c9c8a9a6 --- /dev/null +++ b/docs/reference/config-stacktrace.md @@ -0,0 +1,83 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/config-stacktrace.html +--- + +# Stacktrace configuration options [config-stacktrace] + + +### `ApplicationNamespaces` ([1.5]) [config-application-namespaces] + +This is used to determine whether a stack trace frame is an in-app frame or a library frame. When defined, all namespaces that do not start with one of the values of this collection are ignored when determining error culprit. + +Multiple namespaces can be configured as a comma separated list. For example: `"MyAppA, MyAppB"`. + +This suppresses any configuration of `ExcludedNamespaces`. + +| Default | Type | +| --- | --- | +| | String | + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_APPLICATION_NAMESPACES` | `ElasticApm:ApplicationNamespaces` | + + +### `ExcludedNamespaces` ([1.5]) [config-excluded-namespaces] + +A list of namespaces to exclude when reading an exception StackTrace to determine the culprit. + +Namespaces are checked with `string.StartsWith()`, so "System." matches all System namespaces. + +| Default | Type | +| --- | --- | +| "System., Microsoft., MS., FSharp., Newtonsoft.Json, Serilog, NLog, Giraffe." | String | + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_EXCLUDED_NAMESPACES` | `ElasticApm:ExcludedNamespaces` | + +## `StackTraceLimit` (performance) [config-stack-trace-limit] + +[![dynamic config](../images/dynamic-config.svg "") ](/reference/configuration.md#dynamic-configuration) + +Setting this to `0` disables stack trace collection. Any positive integer value will be used as the maximum number of frames to collect. Setting it to -1 means that all frames will be collected. + +| Default | Type | +| --- | --- | +| `50` | Integer | + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_STACK_TRACE_LIMIT` | `ElasticApm:StackTraceLimit` | + +::::{note} +If you would like to disable stack trace capturing only for spans, but still capture stack traces for errors, set the [`SpanStackTraceMinDuration` (performance)](#config-span-stack-trace-min-duration) config to `-1`. +:::: + + + +### `SpanStackTraceMinDuration` (performance) [config-span-stack-trace-min-duration] + +[![dynamic config](../images/dynamic-config.svg "") ](/reference/configuration.md#dynamic-configuration) + +In its default settings, the APM agent collects a stack trace for every recorded span with duration longer than `5ms`. While this is very helpful to find the exact place in your code that causes the span, collecting this stack trace does have some overhead. When setting this option to zero (regardless of the time unit), like `0ms`, stack traces are collected for all spans. Setting it to a positive value, e.g. `5ms`, limits stack trace collection to spans with durations equal to or longer than the given value, e.g. 5 milliseconds. + +To disable stack trace collection for spans completely, set this option to a negative value, like `-1ms`. + +Supports the duration suffixes `ms`, `s` and `m`. Example: `5ms`. The default unit for this option is `ms` + +| Default | Type | +| --- | --- | +| `5ms` | TimeDuration | + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_SPAN_STACK_TRACE_MIN_DURATION` | `ElasticApm:SpanStackTraceMinDuration` | + +::::{important} +Use of `SpanFramesMinDuration` is deprecated. Use `SpanStackTraceMinDuration`. +:::: + + + diff --git a/docs/reference/config-supportability.md b/docs/reference/config-supportability.md new file mode 100644 index 000000000..e9c7aa11a --- /dev/null +++ b/docs/reference/config-supportability.md @@ -0,0 +1,29 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/config-supportability.html +--- + +# Supportability configuration options [config-supportability] + + +## `LogLevel` [config-log-level] + +[![dynamic config](../images/dynamic-config.svg "") ](/reference/configuration.md#dynamic-configuration) + +Sets the logging level for the agent. + +Valid options: `Critical`, `Error`, `Warning`, `Info`, `Debug`, `Trace` and `None` (`None` disables the logging). + +::::{important} +The `AddElasticApm()` extension enables configuration, as is typical in an ASP.NET Core application. You must instead set the `LogLevel` for the internal APM logger under the `Logging` section of `appsettings.json`. More details, including a [sample configuration file](/reference/configuration-on-asp-net-core.md#sample-config) are available in [Configuration on ASP.NET Core](/reference/configuration-on-asp-net-core.md). +:::: + + +| Environment variable name | IConfiguration or Web.config key | +| --- | --- | +| `ELASTIC_APM_LOG_LEVEL` | `ElasticApm:LogLevel` | + +| Default | Type | +| --- | --- | +| `Error` | String | + diff --git a/docs/reference/configuration-for-windows-services.md b/docs/reference/configuration-for-windows-services.md new file mode 100644 index 000000000..2651fe870 --- /dev/null +++ b/docs/reference/configuration-for-windows-services.md @@ -0,0 +1,29 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/configuration-for-windows-services.html +--- + +# Configuration for Windows Services [configuration-for-windows-services] + +Configuration for Windows services can be provided by setting environment variables for the specific Windows service in the Windows registry. With PowerShell + +```powershell +$environment = [string[]]@( + "ELASTIC_APM_SERVER_URL=http://localhost:8200", <1> + "ELASTIC_APM_TRANSACTION_SAMPLE_RATE=1", + "ELASTIC_APM_ENVIRONMENT=Production", + "ELASTIC_APM_SERVICE_NAME=MyWindowsService") + +Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\ -Name Environment -Value $environment <2> +``` + +1. define the environment variables to use for the Windows service +2. `` is the name of the Windows service. + + +The service must then be restarted for the change to take effect + +```powershell +Restart-Service +``` + diff --git a/docs/reference/configuration-on-asp-net-core.md b/docs/reference/configuration-on-asp-net-core.md new file mode 100644 index 000000000..83247eae1 --- /dev/null +++ b/docs/reference/configuration-on-asp-net-core.md @@ -0,0 +1,76 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/configuration-on-asp-net-core.html +--- + +# Configuration on ASP.NET Core [configuration-on-asp-net-core] + +The `AddElasticApm()` extension method on the `IServiceCollection` automatically accesses configuration bound via the `Microsoft.Extensions.Configuration` sources. To use this type of setup, which is typical in an ASP.NET Core application, your application’s `Program.cs` file should contain code similar to the following: + +```csharp +var builder = WebApplication.CreateBuilder(args); + +builder.Services.AddAllElasticApm(); + +var app = builder.Build(); + +// Configure the HTTP request pipeline. + +app.Run(); +``` + +With this setup, the Agent is able to be configured in the same way as any other library in your application. For example, any configuration source that has been configured on the `IConfiguration` instance in use in the application can be used to set Agent configuration values. + +More information is available in the official [Microsoft .NET Core configuration docs](https://learn.microsoft.com/aspnet/core/fundamentals/configuration) You can find the key for each APM configuration option in this documentation, under the `IConfiguration or Web.config key` column of the option’s description. + +::::{note} +The `AddElasticApm` method only turns on ASP.NET Core monitoring. To turn on tracing for everything supported by the Agent on .NET Core, including HTTP and database monitoring, use the `AddAllElasticApm` method from the `Elastic.Apm NetCoreAll` package. Learn more in [ASP.NET Core setup](/reference/setup-asp-net-core.md). +:::: + + + +## Sample configuration file [sample-config] + +Here is a sample `appsettings.json` configuration file for a typical ASP.NET Core application that has been activated with `AddElasticApm()`. There is one important takeaway, listed as a callout below the example: + +```js +{ + "Logging": { + "LogLevel": { <1> + "Default": "Warning", + "Elastic.Apm": "Debug" + } + }, + "AllowedHosts": "*", + "ElasticApm": + { + "ServerUrl": "http://myapmserver:8200", + "SecretToken": "apm-server-secret-token", + "TransactionSampleRate": 1.0 + } +} +``` + +1. With ASP.NET Core, you must set `LogLevel` for the internal APM logger in the standard `Logging` section with the `Elastic.Apm` category name. + + +In certain scenarios—​like when you’re not using ASP.NET Core—​you won’t activate the agent with the `AddElasticApm()` method. In this case, set the agent log level with [`ElasticApm:LogLevel`](/reference/config-supportability.md#config-log-level), as shown in the following `appsettings.json` file: + +```js +{ + "Logging": { + "LogLevel": { + "Default": "Warning" + } + }, + "AllowedHosts": "*", + "ElasticApm": + { + "LogLevel": "Debug", + "ServerUrl": "http://myapmserver:8200", + "SecretToken": "apm-server-secret-token", + "TransactionSampleRate": 1.0 + } +} +``` + diff --git a/docs/reference/configuration-on-asp-net.md b/docs/reference/configuration-on-asp-net.md new file mode 100644 index 000000000..c64f13817 --- /dev/null +++ b/docs/reference/configuration-on-asp-net.md @@ -0,0 +1,57 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/configuration-on-asp-net.html +--- + +# Configuration on ASP.NET [configuration-on-asp-net] + +When monitoring ASP.NET applications the agent uses two sources of configuration: + +* Web.config `` section +* Environment variables + +Web.config takes precedence over environment variables which means that the agent tries first to find a configuration option value by its key in Web.config. If it’s not present, then the agent tries to look for it among environment variables. If it’s not present, the agent falls back to the options default value. + +You can find the key of each configuration option in the `IConfiguration or Web.config key` column of the corresponding option’s description. + + +## Sample configuration file [asp-net-sample-config] + +Below is a sample `Web.config` configuration file for a ASP.NET application. + +```xml + + + + + + + + + + + + +``` + +Additionally, on ASP.NET, you can implement your own configuration reader. To do this, implement the `IConfigurationReader` interface from the `Elastic.Apm.Config` namespace. Once implemented, you can use the [`FullFrameworkConfigurationReaderType`](#config-full-framework-configuration-reader-type) setting. + + +## `FullFrameworkConfigurationReaderType` [config-full-framework-configuration-reader-type] + +This setting is .NET Full Framework only. + +This setting can point an agent to a custom `IConfigurationReader` implementation and the agent will read configuration from your `IConfigurationReader` implementation. + +Use type name in [AssemblyQualifiedName](https://docs.microsoft.com/en-us/dotnet/api/system.type.assemblyqualifiedname?view=netcore-3.1#System_Type_AssemblyQualifiedName) format (e.g: `MyClass, MyNamespace`). + +| Environment variable name | Web.config key | +| --- | --- | +| `ELASTIC_APM_FULL_FRAMEWORK_CONFIGURATION_READER_TYPE` | `ElasticApm:FullFrameworkConfigurationReaderType` | + +| Default | Type | +| --- | --- | +| None | String | + +If this setting is set in both the web.config file and as an environment variable, then the web.config file has precedence. + diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md new file mode 100644 index 000000000..d9a0f9583 --- /dev/null +++ b/docs/reference/configuration.md @@ -0,0 +1,28 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/configuration.html +--- + +# Configuration [configuration] + +Utilize configuration options to adapt the Elastic APM agent to your needs. There are multiple configuration sources, each with different naming conventions for the property key. + +By default, the agent uses environment variables. Additionally, on ASP.NET Core, the agent plugs into the [Microsoft.Extensions.Configuration](https://learn.microsoft.com/aspnet/core/fundamentals/configuration) infrastructure. + + +## Dynamic configuration [dynamic-configuration] + +Configuration options that are marked with the ![dynamic config](../images/dynamic-config.svg "") badge can be changed at runtime when set from a supported source. + +The .NET Agent supports [Central configuration](docs-content://solutions/observability/apps/apm-agent-central-configuration.md), which allows you to fine-tune certain configurations via the APM app. This feature is enabled in the Agent by default, with [`CentralConfig` ([1.1])](/reference/config-core.md#config-central-config). + + + + + + + + + + + diff --git a/docs/reference/index.md b/docs/reference/index.md new file mode 100644 index 000000000..23b6648bc --- /dev/null +++ b/docs/reference/index.md @@ -0,0 +1,22 @@ +--- +navigation_title: 'APM .NET agent' +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/index.html + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/intro.html +--- + +# APM .NET agent [intro] + +The Elastic APM .NET Agent automatically measures the performance of your application and tracks errors. It has built-in support for the most popular frameworks, as well as a simple API which allows you to instrument any application. + + +## How does the Agent work? [how-it-works] + +The agent auto-instruments [supported technologies](/reference/supported-technologies.md) and records interesting events, like HTTP requests and database queries. To do this, it uses built-in capabilities of the instrumented frameworks like [Diagnostic Source](https://docs.microsoft.com/en-us/dotnet/api/system.diagnostics.diagnosticsource?view=netcore-3.0), an HTTP module for IIS, or [IDbCommandInterceptor](https://docs.microsoft.com/en-us/dotnet/api/system.data.entity.infrastructure.interception.idbcommandinterceptor?view=entity-framework-6.2.0) for Entity Framework. This means that for the supported technologies, there are no code changes required beyond enabling [auto-instrumentation](/reference/set-up-apm-net-agent.md). + +The Agent automatically registers callback methods for built-in Diagnostic Source events. With this, the supported frameworks trigger Agent code for relevant events to measure their duration and collect metadata, like DB statements, as well as HTTP related information, like the URL, parameters, and headers. These events, called Transactions and Spans, are sent to the APM Server. The APM Server converts them to a format suitable for Elasticsearch, and sends them to an Elasticsearch cluster. You can then use the APM app in Kibana to gain insight into latency issues and error culprits within your application. + + +## Additional Components [additional-components] + +APM Agents work in conjunction with the [APM Server](docs-content://solutions/observability/apps/application-performance-monitoring-apm.md), [Elasticsearch](docs-content://get-started/index.md), and [Kibana](docs-content://get-started/the-stack.md). The [APM Guide](docs-content://solutions/observability/apps/application-performance-monitoring-apm.md) provides details on how these components work together, and provides a matrix outlining [Agent and Server compatibility](docs-content://solutions/observability/apps/apm-agent-compatibility.md). diff --git a/docs/reference/log-correlation-manual.md b/docs/reference/log-correlation-manual.md new file mode 100644 index 000000000..c09abb2fb --- /dev/null +++ b/docs/reference/log-correlation-manual.md @@ -0,0 +1,71 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/log-correlation-manual.html +--- + +# Manual log correlation [log-correlation-manual] + +If the agent-provided logging integrations are not suitable or not available for your application, then you can use the agent’s [API](/reference/public-api.md) to inject trace IDs manually. There are two main approaches you can take, depending on whether you are using structured or unstructured logging. + + +## Manual log correlation (structured) [log-correlation-manual-structured] + +For correlating structured logs with traces, the following fields should be added to your logs: + +* `trace.id` +* `transaction.id` + +Given a transaction object, you can obtain its trace id by using the `Transaction.TraceId` property and its transaction id by using the `Transaction.Id` property. + +You can also use the [Elastic.Apm.Agent.Tracer.CurrentTransaction](/reference/public-api.md#api-current-transaction) property anywhere in the code to access the currently active transaction. + +```csharp +public (string traceId, string transactionId) GetTraceIds() +{ + if (!Agent.IsConfigured) return default; + if (Agent.Tracer.CurrentTransaction == null) return default; + return (Agent.Tracer.CurrentTransaction.TraceId, Agent.Tracer.CurrentTransaction.Id); +} +``` + +In case the agent is configured and there is an active transaction, the `traceId` and `transactionId` will always return the current trace and transaction ids that you can manually add to your logs. Make sure you store those in the fields `trace.id` and `transaction.id` when you send them to Elasticsearch. + + +## Manual log correlation (unstructured) [log-correlation-manual-unstructured] + +For correlating unstructured logs (e.g. basic printf-style logging, like `Console.WriteLine`), you will need to include the trace ids in your log message, and then extract them using Filebeat. + +If you already have a transaction object, then you can use the `TraceId` and `Id` properties. Both are of type `string`, so you can simply add them to the log. + +```csharp +var currentTransaction = //Get Current transaction, e.g.: Agent.Tracer.CurrentTransaction; + +Console.WriteLine($"ERROR [trace.id={currentTransaction.TraceId} transaction.id={currentTransaction.Id}] an error occurred"); +``` + +This would print a log message along the lines of: + +``` + ERROR [trace.id=cd04f33b9c0c35ae8abe77e799f126b7 transaction.id=cd04f33b9c0c35ae] an error occurred +``` + +For log correlation to work, the trace ids must be extracted from the log message and stored in separate fields in the Elasticsearch document. This can be achieved by [parsing the data by using ingest node](beats://docs/reference/filebeat/configuring-ingest-node.md), in particular by using [the grok processor](elasticsearch://docs/reference/ingestion-tools/enrich-processor/grok-processor.md). + +```json +{ + "description": "...", + "processors": [ + { + "grok": { + "field": "message", + "patterns": [%{LOGLEVEL:log.level} \\[trace.id=%{TRACE_ID:trace.id}(?: transaction.id=%{SPAN_ID:transaction.id})?\\] %{GREEDYDATA:message}"], + "pattern_definitions": { + "TRACE_ID": "[0-9A-Fa-f]{32}", + "SPAN_ID": "[0-9A-Fa-f]{16}" + } + } + } + ] +} +``` + diff --git a/docs/reference/logs.md b/docs/reference/logs.md new file mode 100644 index 000000000..c3f2bbb78 --- /dev/null +++ b/docs/reference/logs.md @@ -0,0 +1,31 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/logs.html +--- + +# Logs [logs] + +Elastic .NET Agent provides [Log correlation](#log-correlation-ids). The agent will automaticaly inject correlation IDs that allow navigation between logs, traces and services. + +This features is part of [Application log ingestion strategies](docs-content://solutions/observability/logs/stream-application-logs.md). + +The [`ecs-logging-dotnet`](ecs-dotnet://docs/reference/index.md) library can also be used to use the [ECS logging](ecs-logging://docs/reference/intro.md) format without an APM agent. ECS .NET logging will always provide [log correlation](#log-correlation-ids) IDs through [`System.Diagnostics.Activity`](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.activity?view=net-7.0). When paired with the APM Agent it will pick up the appropriate service correlation features too. + + +## Log correlation [log-correlation-ids] + +The Elastic APM .NET agent provides integrations for popular logging frameworks, which take care of injecting trace ID fields into your application’s log records. Currently supported logging frameworks are: + +* [Serilog](/reference/serilog.md) +* [NLog](/reference/nlog.md) + +If your favorite logging framework is not already supported, there are two other options: + +* Open a feature request, or contribute code, for additional support, as described in [CONTRIBUTING.md](https://github.com/elastic/apm-agent-dotnet/blob/main/CONTRIBUTING.md). +* Manually inject trace IDs into log records, as described in [Manual log correlation](/reference/log-correlation-manual.md). + +Regardless of how you integrate APM with logging, you can use [Filebeat](beats://docs/reference/filebeat/filebeat-overview.md) to send your logs to Elasticsearch, in order to correlate your traces and logs and link from APM to the [Logs app](docs-content://solutions/observability/logs/explore-logs.md). + + + + diff --git a/docs/reference/metrics.md b/docs/reference/metrics.md new file mode 100644 index 000000000..7d64e8c20 --- /dev/null +++ b/docs/reference/metrics.md @@ -0,0 +1,210 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/metrics.html +--- + +# Metrics [metrics] + +The .NET agent tracks certain system and application metrics. Some of them have built-in visualizations and some can only be visualized with custom Kibana dashboards. + +These metrics will be sent regularly to the APM Server and from there to Elasticsearch. You can adjust the interval with the setting [`MetricsInterval`](/reference/config-reporter.md#config-metrics-interval). + +The metrics will be stored in the `apm-*` index and have the `processor.event` property set to `metric`. + +"Platform: all" means that the metric is available on every platform where .NET Core is supported. + + +## System metrics [metrics-system] + +As of APM version 6.6, these metrics will be visualized in the APM app. + +::::{important} +System CPU usage metric is collected using Performance Counters on Windows. The account under which a traced application runs must be part of the **Performance Monitor Users** group to be able to access performance counter values. + +An account can be added to the **Performance Monitor Users** group from the command line + +```sh +net localgroup "Performance Monitor Users" "" /add <1> +``` + +1. `` is the account under which the traced application runs + + +For applications running in IIS, [IIS application pool identities use *virtual* accounts](https://docs.microsoft.com/en-us/iis/manage/configuring-security/application-pool-identities) with a name following the convention `IIS APPPOOL\`. An individual application pool identity can be added to the **Performance Monitor Users** group using the `net localgroup` command above. + +:::: + + +For more system metrics, consider installing [metricbeat](beats://docs/reference/metricbeat/metricbeat.md) on your hosts. + +**`system.cpu.total.norm.pct`** +: type: scaled_float + +format: percent + +platform: Windows and Linux only + +The percentage of CPU time in states other than Idle and IOWait, normalized by the number of cores. + + +**`system.process.cpu.total.norm.pct`** +: type: scaled_float + +format: percent + +platform: all + +The percentage of CPU time spent by the process since the last event. This value is normalized by the number of CPU cores and it ranges from 0 to 100%. + + +**`system.memory.total`** +: type: long + +format: bytes + +Platform: Windows and Linux only. + +Total memory. + + +**`system.memory.actual.free`** +: type: long + +format: bytes + +Platform: Windows and Linux only. + +Actual free memory. + + +**`system.process.memory.size`** +: type: long + +format: bytes + +platform: all + +The total virtual memory the process has. + + +**`system.process.memory.rss.bytes`** +: type: long + +format: bytes + +platform: all + +The total physical memory the process has. + + + +## Runtime metrics [metrics-runtime] + +**`clr.gc.count`** +: type: long + +Platform: all. + +The total number of GC collections that have occurred. + + +**`clr.gc.gen0size`** +: type: long + +format: bytes + +Platform: all. + +The size of the generation 0 heap. + + +**`clr.gc.gen1size`** +: type: long + +format: bytes + +Platform: all. + +The size of the generation 1 heap. + + +**`clr.gc.gen2size`** +: type: long + +format: bytes + +Platform: all. + +The size of the generation 2 heap. + + +**`clr.gc.gen3size`** +: type: long + +format: bytes + +Platform: all. + +The size of the generation 3 heap - also known as Large Object Heap (LOH). + + +**`clr.gc.time`** +: type: long + +format: ms + +Platform: all. + +The approximate accumulated collection elapsed time in milliseconds. + + + +## Built-in application metrics [metrics-application] + +To power the [Time spent by span type](docs-content://solutions/observability/apps/transactions-2.md) graph, the agent collects summarized metrics about the timings of spans and transactions, broken down by span type. + +**`transaction.duration`** +: type: simple timer + +This timer tracks the duration of transactions and allows for the creation of graphs displaying a weighted average. + +Fields: + +* `sum.us`: The sum of all transaction durations in microseconds since the last report (the delta) +* `count`: The count of all transactions since the last report (the delta) + +You can filter and group by these dimensions: + +* `transaction.name`: The name of the transaction +* `transaction.type`: The type of the transaction, for example `request` + + +**`transaction.breakdown.count`** +: type: long + +format: count (delta) + +The number of transactions for which breakdown metrics (`span.self_time`) have been created. As the Java agent tracks the breakdown for both sampled and non-sampled transactions, this metric is equivalent to `transaction.duration.count` + +You can filter and group by these dimensions: + +* `transaction.name`: The name of the transaction +* `transaction.type`: The type of the transaction, for example `request` + + +**`span.self_time`** +: type: simple timer + +This timer tracks the span self-times and is the basis of the transaction breakdown visualization. + +Fields: + +* `sum.us`: The sum of all span self-times in microseconds since the last report (the delta) +* `count`: The count of all span self-times since the last report (the delta) + +You can filter and group by these dimensions: + +* `transaction.name`: The name of the transaction +* `transaction.type`: The type of the transaction, for example `request` +* `span.type`: The type of the span, for example `app`, `template` or `db` +* `span.subtype`: The sub-type of the span, for example `mysql` (optional) diff --git a/docs/reference/nlog.md b/docs/reference/nlog.md new file mode 100644 index 000000000..5cf0de548 --- /dev/null +++ b/docs/reference/nlog.md @@ -0,0 +1,32 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/nlog.html +--- + +# NLog [nlog] + +For NLog, we offer two [LayoutRenderers](https://github.com/NLog/NLog/wiki/Layout-Renderers) that inject the current trace and transaction id into logs. + +In order to use them, you need to add the [Elastic.Apm.NLog](https://www.nuget.org/packages/Elastic.Apm.NLog) NuGet package to your application and load it in the `` section of your NLog config file: + +```xml + + + + + + + + + + + + + + + + +``` + +As you can see in the sample file above, you can reference the current transaction id with `${ElasticApmTransactionId}` and the trace id with `${ElasticApmTraceId}`. + diff --git a/docs/reference/nuget-packages.md b/docs/reference/nuget-packages.md new file mode 100644 index 000000000..e9815d8e5 --- /dev/null +++ b/docs/reference/nuget-packages.md @@ -0,0 +1,78 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/packages.html +--- + +# NuGet packages [packages] + +Agent instrumentations are released as a set of NuGet packages available on [nuget.org](https://nuget.org). You can add the Agent and specific instrumentations to your .NET application by referencing one or more of these packages. + + +## Get started [_get_started_2] + +* [Azure Cosmos DB](/reference/setup-azure-cosmosdb.md) +* [Azure Service Bus](/reference/setup-azure-servicebus.md) +* [Azure Storage](/reference/setup-azure-storage.md) +* [Entity Framework 6](/reference/setup-ef6.md) +* [Entity Framework Core](/reference/setup-ef-core.md) +* [Elasticsearch](/reference/setup-elasticsearch.md) +* [gRPC](/reference/setup-grpc.md) +* [MongoDB](/reference/setup-mongo-db.md) +* [SqlClient](/reference/setup-sqlclient.md) +* [StackExchange.Redis](/reference/setup-stackexchange-redis.md) + + +## Packages [_packages] + +The following NuGet packages are available: + +[**Elastic.Apm**](https://www.nuget.org/packages/Elastic.Apm) +: The core agent package, containing the [*Public API*](/reference/public-api.md) of the agent. It also contains every tracing component to trace classes that are part of .NET Standard 2.0, which includes the monitoring part for `HttpClient`. Every other Elastic APM package references this package. + +[**Elastic.Apm.NetCoreAll**](https://www.nuget.org/packages/Elastic.Apm.NetCoreAll) +: A meta package that references all other Elastic APM .NET agent package that can automatically configure instrumentation. + + If you plan to monitor a typical ASP.NET Core application that depends on the [Microsoft.AspNetCore.All](https://www.nuget.org/packages/Microsoft.AspNetCore.All) package, you should reference this package. + + In order to avoid adding unnecessary dependencies in applications that aren’t dependent on the [Microsoft.AspNetCore.All](https://www.nuget.org/packages/Microsoft.AspNetCore.All) package, we also offer some other packages - those are all referenced by the `Elastic.Apm.NetCoreAll` package. + + +[**Elastic.Apm.Extensions.Hosting**](https://www.nuget.org/packages/Elastic.Apm.Extensions.Hosting) ([1.6.0-beta]) +: A package for agent registration integration with `Microsoft.Extensions.Hosting.IHostBuilder` registration. + +$$$setup-asp-net$$$ + +[Elastic.Apm.AspNetCore](/reference/setup-asp-net-core.md) +: A package for instrumenting ASP.NET Core applications. The main difference between this package and the `Elastic.Apm.NetCoreAll` package is that this package only instruments ASP.NET Core by default, whereas `Elastic.Apm.NetCoreAll` instruments all components that can be automatically configured, such as Entity Framework Core, HTTP calls with `HttpClient`, database calls to SQL Server with `SqlClient`, etc. Additional instrumentations can be added when using `Elastic.Apm.AspNetCore` by referencing the respective NuGet packages and including their configuration code in agent setup. + +[**Elastic.Apm.AspNetFullFramework**](/reference/setup-asp-dot-net.md) +: A package containing ASP.NET .NET Framework instrumentation. + +[**Elastic.Apm.Azure.CosmosDb**](/reference/setup-azure-cosmosdb.md) +: A package containing instrumentation to capture spans for Azure Cosmos DB with [Microsoft.Azure.Cosmos](https://www.nuget.org/packages/Microsoft.Azure.Cosmos), [Microsoft.Azure.DocumentDb](https://www.nuget.org/packages/Microsoft.Azure.DocumentDb), and [Microsoft.Azure.DocumentDb.Core](https://www.nuget.org/packages/Microsoft.Azure.DocumentDb.Core) packages. + +[**Elastic.Apm.Azure.ServiceBus**](/reference/setup-azure-servicebus.md) +: A package containing instrumentation to capture transactions and spans for messages sent and received from Azure Service Bus with [Microsoft.Azure.ServiceBus](https://www.nuget.org/packages/Microsoft.Azure.ServiceBus/) and [Azure.Messaging.ServiceBus](https://www.nuget.org/packages/Azure.Messaging.ServiceBus/) packages. + +[**Elastic.Apm.Azure.Storage**](/reference/setup-azure-storage.md) +: A package containing instrumentation to capture spans for interaction with Azure Storage with [Azure.Storage.Queues](https://www.nuget.org/packages/azure.storage.queues/), [Azure.Storage.Blobs](https://www.nuget.org/packages/azure.storage.blobs/) and [Azure.Storage.Files.Shares](https://www.nuget.org/packages/azure.storage.files.shares/) packages. + +[**Elastic.Apm.EntityFrameworkCore**](/reference/setup-ef-core.md) +: A package containing Entity Framework Core instrumentation. + +[**Elastic.Apm.EntityFramework6**](/reference/setup-ef6.md) +: A package containing an interceptor to automatically create spans for database operations executed by Entity Framework 6 on behalf of the application. + +[**Elastic.Apm.MongoDb**](/reference/setup-mongo-db.md) +: A package containing support for [MongoDB.Driver](https://www.nuget.org/packages/MongoDB.Driver/). + +[**Elastic.Apm.SqlClient**](/reference/setup-sqlclient.md) +: A package containing [System.Data.SqlClient](https://www.nuget.org/packages/System.Data.SqlClient) and [Microsoft.Data.SqlClient](https://www.nuget.org/packages/Microsoft.Data.SqlClient) instrumentation. + +::::{note} +this functionality now included by default in `Elastic.Apm` as of 1.24.0 +:::: + + +[**Elastic.Apm.StackExchange.Redis**](/reference/setup-stackexchange-redis.md) +: A package containing instrumentation to capture spans for commands sent to redis with [StackExchange.Redis](https://www.nuget.org/packages/StackExchange.Redis/) package. diff --git a/docs/reference/opentelemetry-bridge.md b/docs/reference/opentelemetry-bridge.md new file mode 100644 index 000000000..6471291c6 --- /dev/null +++ b/docs/reference/opentelemetry-bridge.md @@ -0,0 +1,126 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/opentelemetry-bridge.html +--- + +# OpenTelemetry bridge [opentelemetry-bridge] + +The OpenTelemetry Bridge in the Elastic .NET APM Agent bridges OpenTelemetry spans into Elastic APM transactions and spans. The Elastic APM OpenTelemetry bridge allows you to use the vendor-neutral OpenTelemetry Tracing API to manually instrument your code and have the Elastic .NET APM agent handle those API calls. This means you can use the Elastic APM agent for tracing, without any vendor lock-in from adding manual tracing using the APM agent’s own [Public API](/reference/public-api.md). + + +## Getting started [otel-getting-started] + +The OpenTelemetry bridge is part of the core agent package ([`Elastic.Apm`](https://www.nuget.org/packages/Elastic.Apm)), so you don’t need to add an additional dependency. + + +### Disabling the OpenTelemetry Bridge [otel-enable-bridge] + +The OpenTelemetry bridge is enabled out of the box starting version `1.23.0`. + +This allows you to instrument code through `ActivitySource` and `StartActivity()` without any additional configuration. + +If you want to disable the bridge you can disable it for now through the [OpenTelemetryBridgeEnabled](/reference/config-core.md#config-opentelemetry-bridge-enabled) configuration setting. + +If you configured the agent via environment variables, set the `ELASTIC_APM_OPENTELEMETRY_BRIDGE_ENABLED` environment variable to `false`. + +If you configured the agent via the `appsettings.json` file, then set `ElasticApm:OpenTelemetryBridgeEnabled` to `false`. + +```js +{ + "ElasticApm": + { + "ServerUrl": "http://myapmserver:8200", + "SecretToken": "apm-server-secret-token", + "OpenTelemetryBridgeEnabled": false + } +} +``` + + +### Create an ActivitySource and start spans [create-activity-source-and-spans] + +You can create OpenTelemetry spans, or in .NET terminology, you can start creating new activities via the activity source, and the agent will bridge those spans automatically. + +```csharp +public static void Sample() +{ + var src = new ActivitySource("Test"); + using var activity1 = src.StartActivity(nameof(Sample), ActivityKind.Server); + Thread.Sleep(100); + using var activity2 = src.StartActivity("foo"); + Thread.Sleep(150); +} +``` + +The code snippet above creates a span named `Sample` and a child span on `Sample` named `foo`. The bridge will create a transaction from `Sample` and a child span named `foo`. + + +### Mixing OpenTelemetry and the Elastic APM Public API [mixing-apis] + +You can also mix the Activity API with the [Public API](/reference/public-api.md), the OpenTelemetry bridge will take care of putting the spans into the right place. The advantage of this is that if you already have some libraries that you instrumented via the [Public API](/reference/public-api.md), but going forward, you’d like to use the vendor-independent OpenTelemetry API, you don’t need to replace all Public API calls in one go. + +```csharp +/// ElasticTransaction +/// - +/// ---> OTelSpan +/// - +/// ---> ElasticSpan + +var src = new ActivitySource("Test"); +tracer.CaptureTransaction( nameof(Sample4), "test", t => +{ + Thread.Sleep(100); + using (var activity = src.StartActivity("foo")) + { + tracer.CurrentSpan.CaptureSpan("ElasticApmSpan", "test", () => Thread.Sleep(50)); + Thread.Sleep(150); + } +}); +``` + +The code snippet above creates a transaction with the Elastic .NET APM Agent’s [Public API](/reference/public-api.md). Then it creates an activity called `foo`; this activity will be a child of the previously created transaction. Finally, a span is created again using the Elastic .NET APM Agent’s [Public API](/reference/public-api.md); this span will be a child span of the OpenTelemetry span. + +Of course these calls don’t have to be in the same method. The concept described here works across different methods, types, or libraries. + + +### Baggage support [baggage-api] + +The Elastic APM Agent also integrates with [Activity.Baggage](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.activity.baggage?view=net-6.0#system-diagnostics-activity-baggage). + +Here is an example that sets a baggage value with the above API: + +```csharp +_activitySource.StartActivity("MyActivity")?.AddBaggage("foo", "bar"); +``` + +The Elastic APM Agent will automatically propagate such values according to the [W3C Baggage specification](https://www.w3.org/TR/baggage/) and `Activity.Baggage` is automatically populated based on the incoming `baggage` header. + +Furthermore, the agent offers the [BaggageToAttach](/reference/config-http.md#config-baggage-to-attach) configuration to automatically attach values from `Activity.Baggage` to captured events. + + +### Supported OpenTelemetry implementations [supported-opentelemetry-implementations] + +OpenTelemetry in .NET is implemented via the [Activity API](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.activity?view=net-6.0) and there is an [OpenTelemetry shim](https://opentelemetry.io/docs/instrumentation/net/shim/) which follows the OpenTelemetry specification more closer. This shim is built on top of the Activity API. + +The OpenTelemetry bridge in the Elastic .NET APM Agent targets the [Activity API](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.activity?view=net-6.0). Since the [OpenTelemetry .NET shim](https://opentelemetry.io/docs/instrumentation/net/shim/) builds on top of the [Activity API](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.activity?view=net-6.0), the shim is implicitly supported as well, although we don’t directly test it, because the Activity API is the recommended OpenTelemetry API for .NET. + + +## Caveats [otel-caveats] + +Not all features of the OpenTelemetry API are supported. + + +#### Metrics [otel-metrics] + +This bridge only supports the tracing API. The Metrics API is currently not supported. + + +#### Span Events [otel-span-events] + +Span events ([`Span#addEvent()`](https://open-telemetry.github.io/opentelemetry-js-api/interfaces/span.md#addevent)) are not currently supported. Events will be silently dropped. + + +#### Baggage [otel-baggage] + +[Propagating baggage](https://open-telemetry.github.io/opentelemetry-js-api/classes/propagationapi.md) within or outside the process is not supported. Baggage items are silently dropped. + diff --git a/docs/reference/performance-tuning.md b/docs/reference/performance-tuning.md new file mode 100644 index 000000000..31903d254 --- /dev/null +++ b/docs/reference/performance-tuning.md @@ -0,0 +1,56 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/performance-tuning.html +--- + +# Performance tuning [performance-tuning] + +There are many options available to tune agent performance. Which option to adjust depends on whether you are optimizing for speed, memory usage, bandwidth or storage. + + +## Sampling [performance-tuning-sampling] + +The first knob to reach for when tuning the performance of the agent is [`TransactionSampleRate`](/reference/config-core.md#config-transaction-sample-rate). Adjusting the sample rate controls what percent of requests are traced. By default, the sample rate is set at `1.0`, meaning *all* requests are traced. + +The sample rate will impact all four performance categories, so simply turning down the sample rate is an easy way to improve performance. + +Here’s an example of setting the sample rate to 20% using [Configuration on ASP.NET Core](/reference/configuration-on-asp-net-core.md): + +```js +{ + "ElasticApm": { + "TransactionSampleRate": 0.2 + } +} +``` + + +## Stack traces [performance-tuning-stack-traces] + +In a complex application, a request may produce many spans. Capturing a stack trace for every span can result in significant memory usage. Stack traces are also captured for every error. There are several settings to adjust how stack traces are captured. + + +### Disable capturing stack traces [performance-tuning-disable-capturing-stack-traces] + +To disable capturing stack traces (for both spans and errors), set [`StackTraceLimit`](/reference/config-stacktrace.md#config-stack-trace-limit) to `0`. + + +### Capture stack traces only for long running spans [performance-tuning-stack-traces-for-long-running-spans] + +In its default settings, the APM agent collects a stack trace for every recorded span with duration longer than 5ms. To increase the duration threshold, set [`SpanStackTraceMinDuration`](/reference/config-stacktrace.md#config-span-stack-trace-min-duration). + + +### Reduce number of captured stack trace frames [performance-tuning-stack-frame-limit] + +The [`StackTraceLimit`](/reference/config-stacktrace.md#config-stack-trace-limit) controls how many stack frames should be collected when a capturing stack trace. + + +## Disable capturing HTTP request and response headers [performance-tuning-disable-capture-headers] + +Capturing HTTP request and response headers increases memory allocations, network bandwidth and disk space used by Elasticsearch. To disable capturing HTTP request and response headers, set [`CaptureHeaders`](/reference/config-http.md#config-capture-headers) to `false`. + + +## Increase metrics collection interval [performance-tuning-increase-metrics-collection-interval] + +The .NET agent tracks certain system and application metrics. These metrics are regularly collected and sent to the APM Server and from there to Elasticsearch. You can adjust the interval for metrics collection with the setting [`MetricsInterval`](/reference/config-reporter.md#config-metrics-interval). + diff --git a/docs/reference/public-api.md b/docs/reference/public-api.md new file mode 100644 index 000000000..72287a96a --- /dev/null +++ b/docs/reference/public-api.md @@ -0,0 +1,841 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/public-api.html +--- + +# Public API [public-api] + +The public API of the Elastic APM .NET agent lets you customize and manually create spans and transactions, as well as track errors. + + +## Initialization [api-initialization] + +The API does not require explicit Agent initialization—agent initialization is optional. The `Elastic.Apm.Agent.IsConfigured` property lets you check whether the agent is already initialized. + + +### Implicit agent initialization [implicit-initialization] + +If you don’t explicitly initialize the agent, it will be started with a default component setup. This means the Agent will read [configuration settings](/reference/configuration.md) from environment variables. If you don’t set an environment variable, the Agent will use the default value. For example, the `ServerUrl` default is `http://localhost:8200`. + +This implicit initialization of the agent happens on the first call on the `Elastic.Apm.Agent` class. + +::::{note} +One exception is the `Elastic.Apm.Agent.IsConfigured` method. This method never initializes the agent, it only checks if the agent is already initialized. +:::: + + +Another example of initialization is when you enable the Agent with one of the technology-specific methods from the [*Set up the Agent*](/reference/set-up-apm-net-agent.md) instructions. Specifically when the `AddElasticApm` or `AddAllElasticApm` method is called in ASP.NET Core or when the IIS module is initialized in an IIS application. + +The default agent setup should cover most of the use cases and the primary way to configure the agent is through environment variables. + + +### Explicit agent initialization [explicit-initialization] + +If you would like to replace one of the agent components, you can do so by calling the `Elastic.Apm.Agent.Setup(AgentComponents)` method. In the AgentComponents you can pass following optional components to the agent: + +* `IApmLogger`: A logger implementation that will be used to print log messages. Default: A console logger. +* `IPayloadSender`: A component that receives all the captured events like spans, transactions, and metrics. The default implementation serializes all events and sends them to the Elastic APM Server +* `IConfigurationReader`: A component that reads [agent configuration settings](/reference/configuration.md). The default implementation reads configuration through environment variables. + +::::{note} +In the case of ASP.NET Core, when you register the agent, the `AddElasticApm` and the `AddAllElasticApm` methods both implicitly initialize the agent by calling the `Elastic.Apm.Agent.Setup` method internally. In that setup, the `IConfigurationReader` implementation will read configuration from the ASP.NET Core configuration system in case you pass an `IConfiguration` instance to the method. The `IApmLogger` instance will also log through the configured logging provider by integrating into the ASP.NET Core logging system. +:::: + + + +## Auto instrumentation in combination with the Public Agent API [auto-instrumentation-and-agent-api] + +With the `Elastic.Apm.Agent.Subscribe(params IDiagnosticsSubscriber[] subscribers)` method you can turn on auto instrumentation for supported libraries. + +In the case of ASP.NET Core, when you turn on the agent with the `AddAllElasticApm` method, the agent will do this automatically. + +With a typical console application, you need to do this manually by calling `Elastic.Apm.Agent.Subscribe(params IDiagnosticsSubscriber[] subscribers)` method somewhere in your application, ideally in the startup code. + +`IDiagnosticsSubscriber` implementations are offered by the agent and they subscribe to diagnostic source events or other data sources in order to capture events automatically. + +Some examples: + +* $$$setup-http$$$`HttpDiagnosticsSubscriber`: captures HTTP calls through `HttpClient` and `HttpWebRequest` + + ```csharp + Agent.Subscribe(new HttpDiagnosticsSubscriber()); + ``` + +* `EfCoreDiagnosticsSubscriber`: captures database calls through Entity Framework Core +* `SqlClientDiagnosticSubscriber`: captures database calls through `SqlClient` + +::::{note} +When the agent is configured with [`Enabled` set to `false`](/reference/config-core.md#config-enabled), `Elastic.ApmAgent.Subscribe(params IDiagnosticsSubscriber[] subscribers)` will not subscribe the subscribers to diagnostic source events. + +:::: + + + +## Tracer API [api-tracer-api] + +The tracer gives you access to the currently active transaction and it enables you to manually start a transaction. + +You can access the API by using the static property on the Agent: `Elastic.Apm.Agent.Tracer`. + + +#### `ITransaction StartTransaction(string name, string type, DistributedTracingData = null)` [api-start-transaction] + +Use this method to create a custom transaction. + +Note that in the case of auto-instrumentation, the agent will automatically do this for you. For example, if you have incoming HTTP calls in an ASP.NET Core application, the agent automatically starts a transaction. In these instances, this method is not needed. + +It’s important to call [`void End()`](#api-transaction-end) when the transaction has ended. A best practice is to use the transaction in a try-catch-finally block or to use the [`CaptureTransaction`](#convenient-capture-transaction) method. + +Example: + +```csharp +var transaction = Elastic.Apm.Agent + .Tracer.StartTransaction("MyTransaction", ApiConstants.TypeRequest); +try +{ + //application code that is captured as a transaction +} +catch (Exception e) +{ + transaction.CaptureException(e); + throw; +} +finally +{ + transaction.End(); +} +``` + + +#### `ITransaction CurrentTransaction` [api-current-transaction] + +Returns the currently active transaction. See the [Transaction API](#api-transaction) to customize the current transaction. + +If there is no current transaction, this method will return `null`. + +```csharp +var transaction = Elastic.Apm.Agent.Tracer.CurrentTransaction; +``` + + +#### `ISpan CurrentSpan` [api-current-span] + +Returns the currently active span. See the [Span API](#api-span) to customize the current span. + +If there is no current span, this method will return `null`. + +```csharp +var span = Elastic.Apm.Agent.Tracer.CurrentSpan; +``` + + +#### `CaptureTransaction` [convenient-capture-transaction] + +This is a convenient method which starts and ends a transaction and captures unhandled exceptions. It has 3 required parameters: + +* `name`: The name of the transaction +* `type` The type of the transaction +* One of the following types which references the code that you want to capture as a transaction: + + * `Action` + * `Action` + * `Func` + * `Func` + * `Func` + * `Func` + * `Func>` + * `Func>` + + +And an optional parameter: + +* `distributedTracingData`: A `DistributedTracingData` instance that contains the distributed tracing information in case you want the new transaction to be a part of a trace. + +The following code is the equivalent of the previous example with the convenient API. It automatically starts and ends the transaction and reports unhandled exceptions. The `t` parameter gives you access to the `ITransaction` instance which represents the transaction that you just created. + +```csharp +Elastic.Apm.Agent.Tracer + .CaptureTransaction("TestTransaction", ApiConstants.TypeRequest, (t) => +{ + //application code that is captured as a transaction +}); +``` + +This API also supports `async` methods with the `Func` overloads. + +::::{note} +The duration of the transaction will be the timespan between the first and the last line of the `async` lambda expression. +:::: + + +Example: + +```csharp +await Elastic.Apm.Agent.Tracer + .CaptureTransaction("TestTransaction", "TestType", async () => +{ + //application code that is captured as a transaction + await Task.Delay(500); //sample async code +}); +``` + +::::{note} +Return value of [`CaptureTransaction`](#convenient-capture-transaction) method overloads that accept Task (or Task) is the same Task (or Task) instance as the one passed as the argument so if your application should continue only after the task completes you have to call [`CaptureTransaction`](#convenient-capture-transaction) with `await` keyword. +:::: + + + +#### Manually propagating distributed tracing context [manually-propagating-distributed-tracing-context] + +Agent automatically propagates distributed tracing context for the supported technologies (see [Networking client-side technologies](/reference/supported-technologies.md#supported-networking-client-side-technologies)). If your application communicates over a protocol that is not supported by the agent you can manually propagate distributed tracing context from the caller to the callee side using Public Agent API. + +First you serialize distributed tracing context on the caller side: + +```csharp +string outgoingDistributedTracingData = + (Agent.Tracer.CurrentSpan?.OutgoingDistributedTracingData + ?? Agent.Tracer.CurrentTransaction?.OutgoingDistributedTracingData)?.SerializeToString(); +``` + +Then you transfer the resulted string to the callee side and you continue the trace by passing deserialized distributed tracing context to any of [`ITransaction StartTransaction(string name, string type, DistributedTracingData = null)`](#api-start-transaction) or [`CaptureTransaction`](#convenient-capture-transaction) APIs - all of these APIs have an optional `DistributedTracingData` parameter. For example: + +```csharp +var transaction2 = Agent.Tracer.StartTransaction("Transaction2", "TestTransaction", + DistributedTracingData.TryDeserializeFromString(serializedDistributedTracingData)); +``` + +::::{note} +The `OutgoingDistributedTracingData` property can be `null`. One such scenario is when the agent is disabled. +:::: + + + +#### `void CaptureError(string message, string culprit, StackFrame[] frames = null, string parentId = null);` [api-start-capture-error] + +Use this method to capture an APM error with a message and a culprit. + +::::{note} +Captured errors are automatically correlated with the active transaction. If no transaction is active, the error will still appear in the APM app but will not be correlated with a transaction. +:::: + + +Example: + +```csharp +Agent.Tracer.CaptureError("Something went wrong", "Database issue"); +``` + + +#### `void CaptureException(Exception exception, string culprit = null, bool isHandled = false, string parentId = null);` [api-start-capture-exception] + +Use this method to capture a .NET exception as an APM error. + +::::{note} +Captured errors are automatically correlated with the active transaction. If no transaction is active, the error will still appear in the APM app but will not be correlated with a transaction. +:::: + + +Example: + +```csharp +try +{ + //run my code +} +catch (Exception e) +{ + Agent.Tracer.CaptureException(e); + //handle error +} +``` + + +#### `void CaptureErrorLog(ErrorLog errorLog, string parentId = null, Exception exception = null);` [api-start-capture-error-log] + +Use this method to capture a log event as an APM error. + +::::{note} +Captured errors are automatically correlated with the active transaction. If no transaction is active, the error will still appear in the APM app but will not be correlated with a transaction. +:::: + + +Example: + +```csharp +var errorLog = new ErrorLog("Error message") +{ + Level = "error", + ParamMessage = "42" +}; + +Agent.Tracer.CaptureErrorLog(errorLog); +``` + + +## Transaction API [api-transaction] + +A transaction describes an event captured by an Elastic APM agent monitoring a service. Transactions help combine multiple [Spans](#api-span) into logical groups, and they are the first [Span](#api-span) of a service. More information on Transactions and Spans is available in the [APM data model](docs-content://solutions/observability/apps/learn-about-application-data-types.md) documentation. + +See [`ITransaction CurrentTransaction`](#api-current-transaction) on how to get a reference of the current transaction. + +::::{note} +Calling any of the transaction’s methods after [`void End()`](#api-transaction-end) has been called is illegal. You may only interact with a transaction when you have control over its lifecycle. +:::: + + + +#### `ISpan StartSpan(string name, string type, string subType = null, string action = null)` [api-transaction-create-span] + +Start and return a new custom span as a child of the given transaction. + +It is important to call [`void End()`](#api-span-end) when the span has ended or to use the [`CaptureSpan`](#convenient-capture-span) method. A best practice is to use the span in a try-catch-finally block. + +Example: + +```csharp +ISpan span = transaction.StartSpan("Select FROM customer", + ApiConstants.TypeDb, ApiConstants.SubtypeMssql, ApiConstants.ActionQuery); +try +{ + //execute db query +} +catch(Exception e) +{ + span.CaptureException(e); + throw; +} +finally +{ + span.End(); +} +``` + + +#### `void SetLabel(string key, T value)` [1.7.0] [api-transaction-set-label] + +Labels are used to add **indexed** information to transactions, spans, and errors. Indexed means the data is searchable and aggregatable in Elasticsearch. Multiple labels can be defined with different key-value pairs. + +* Indexed: Yes +* Elasticsearch type: [object](elasticsearch://docs/reference/elasticsearch/mapping-reference/object.md) +* Elasticsearch field: `labels` (previously `context.tags` in (string key, out T value)` [1.7.1] [api-transaction-try-get-label] + +Returns the transaction’s label in the `value` out parameter. If the `key` does not exist, this method returns false. Labels can be added with the [SetLabel](#api-transaction-set-label) method. + +```csharp +if(transaction.TryGetLabel("foo", our var myLabel)) + Console.WriteLine(myLabel); +``` + + +#### `Dictionary Labels` [api-transaction-tags] + +::::{warning} +This property is obsolete and will be be removed in a future version. Use the [`void SetLabel()`](#api-transaction-set-label) method instead, which allows setting labels of string, boolean and number. This property remains for now in order to not break binary compatibility, and at serialization time, the values set with `.SetLabel()` are combined with `Labels` to form the set of labels sent to APM server, with values in `Labels` taking precedence. +:::: + + +A flat mapping of user-defined labels with string values. + +If the key contains any special characters (`.`,`*`, `"`), they will be replaced with underscores. For example `a.b` will be stored as `a_b`. + +::::{tip} +Before using custom labels, ensure you understand the different types of [metadata](docs-content://solutions/observability/apps/metadata.md) that are available. +:::: + + +::::{warning} +Avoid defining too many user-specified labels. Defining too many unique fields in an index is a condition that can lead to a [mapping explosion](docs-content://manage-data/data-store/mapping.md#mapping-limit-settings). +:::: + + +```csharp +Agent.Tracer + .CaptureTransaction(TransactionName, TransactionType, + transaction => + { + transaction.Labels["foo"] = "bar"; + //application code that is captured as a transaction + }); +``` + +* `key`: The label key +* `value`: The label value + + +#### `void End()` [api-transaction-end] + +Ends the transaction and schedules it to be reported to the APM Server. + +It is illegal to call any methods on a span instance which has already ended. This also includes this method and [`ISpan StartSpan(string name, string type, string subType = null, string action = null)`](#api-transaction-create-span). + +Example: + +```csharp +transaction.End(); +``` + +::::{note} +If you use the [`CaptureTransaction`](#convenient-capture-transaction) method you must not call [`void End()`](#api-transaction-end). +:::: + + + +#### `void CaptureException(Exception e)` [api-transaction-capture-exception] + +Captures an exception and reports it to the APM server. + + +#### `void CaptureError(string message, string culprit, StackFrame[] frames)` [api-transaction-capture-error] + +Captures a custom error and reports it to the APM server. + +This method is typically used when you want to report an error, but you don’t have an `Exception` instance. + + +#### `void CaptureErrorLog(ErrorLog errorLog, string parentId = null, Exception exception = null);` [api-transaction-capture-error-log] + +Captures a custom error and reports it to the APM server with a log attached to it. + +This method is typically used when you already log errors in your code and you want to attach this error to an APM transaction. The log will show up on the APM UI as part of the error and it will be correlated to the transaction. + + +#### `CaptureSpan` [convenient-capture-span] + +This is a convenient method which starts and ends a span on the given transaction and captures unhandled exceptions. It has the same overloads as the [`CaptureTransaction`](#convenient-capture-transaction) method. + +It has 3 required parameters: + +* `name`: The name of the span +* `type` The type of the span +* One of the following types which references the code that you want to capture as a transaction: + + * `Action` + * `Action` + * `Func` + * `Func` + * `Func` + * `Func` + * `Func>` + * `Func>` + + +and 2 optional parameters: + +* `supType`: The subtype of the span +* `action`: The action of the span + +The following code is the equivalent of the previous example from the [`ISpan StartSpan(string name, string type, string subType = null, string action = null)`](#api-transaction-create-span) section with the convenient API. It automatically starts and ends the span and reports unhandled exceptions. The `s` parameter gives you access to the `ISpan` instance which represents the span that you just created. + +```csharp +ITransaction transaction = Elastic.Apm.Agent.Tracer.CurrentTransaction; + +transaction.CaptureSpan("SampleSpan", ApiConstants.TypeDb, (s) => +{ + //execute db query +}, ApiConstants.SubtypeMssql, ApiConstants.ActionQuery); +``` + +Similar to the [`CaptureTransaction`](#convenient-capture-transaction) API, this method also supports `async` methods with the `Func` overloads. + +::::{note} +The duration of the span will be the timespan between the first and the last line of the `async` lambda expression. +:::: + + +This example shows you how to track an `async` code block that returns a result (`Task`) as a span: + +```csharp +ITransaction transaction = Elastic.Apm.Agent.Tracer.CurrentTransaction; +var asyncResult = await transaction.CaptureSpan("Select FROM customer", ApiConstants.TypeDb, async(s) => +{ + //application code that is captured as a span + await Task.Delay(500); //sample async code + return 42; +}); +``` + +::::{note} +Return value of [`CaptureSpan`](#convenient-capture-span) method overloads that accept Task (or Task) is the same Task (or Task) instance as the one passed as the argument so if your application should continue only after the task completes you have to call [`CaptureSpan`](#convenient-capture-span) with `await` keyword. +:::: + + +::::{note} +Code samples above use `Elastic.Apm.Agent.Tracer.CurrentTransaction`. In production code you should make sure the `CurrentTransaction` is not `null`. +:::: + + + +#### `EnsureParentId` [api-transaction-ensure-parent-id] + +If the transaction does not have a ParentId yet, calling this method generates a new ID, sets it as the ParentId of this transaction, and returns it as a `string`. + +This enables the correlation of the spans the JavaScript Real User Monitoring (RUM) agent creates for the initial page load with the transaction of the backend service. + +If your service generates the HTML page dynamically, initializing the JavaScript RUM agent with the value of this method allows analyzing the time spent in the browser vs in the backend services. + +To enable the JavaScript RUM agent in ASP.NET Core, initialize the RUM agent with the .NET agent’s current transaction: + +```JavaScript + +``` + +See the [JavaScript RUM agent documentation](apm-agent-rum-js://docs/reference/index.md) for more information. + + +#### `Dictionary Custom` [api-transaction-custom] + +Custom context is used to add non-indexed, custom contextual information to transactions. Non-indexed means the data is not searchable or aggregatable in Elasticsearch, and you cannot build dashboards on top of the data. However, non-indexed information is useful for other reasons, like providing contextual information to help you quickly debug performance issues or errors. + +If the key contains any special characters (`.`,`*`, `"`), they will be replaced with underscores. For example `a.b` will be stored as `a_b`. + +Unlike [`Dictionary Labels`](#api-transaction-tags), the data in this property is not trimmed. + +```csharp +Agent.Tracer.CaptureTransaction(transactionName, transactionType, (transaction) => +{ + transaction.Custom["foo"] = "bar"; + transaction.End(); +}); +``` + + +#### `void SetService(string serviceName, string serviceVersion)` ([1.7]) [api-transaction-set-service] + +Overwrite the service name and version on a per transaction basis. This is useful when you host multiple services in a single process. + +When not set, transactions are associated with the default service. + +This method has two `string` parameters: + +* `serviceName`: The name of the service to associate with the transaction. +* `serviceVersion`: The version of the service to associate with the transaction. + +Usage: + +```csharp +var transaction = agent.Tracer.StartTransaction("Transaction1", "sample"); +transaction.SetService("MyServiceName", "1.0-beta1"); +``` + +It can also be used with the [Filter API ([1.5])](#filter-api): + +```csharp +Agent.AddFilter( transaction => +{ + transaction.SetService("MyServiceName", "1.0-beta1"); + return transaction; +}); +``` + + +#### `Context` [api-transaction-context] + +You can attach additional context to manually captured transactions. + +If you use a web framework for which agent doesn’t capture transactions automatically (see [Web frameworks](/reference/supported-technologies.md#supported-web-frameworks)), you can add context related to the captured transaction by setting various properties of transaction’s `Context` property. For example: + +```csharp +Agent.Tracer.CaptureTransaction("MyCustomTransaction",ApiConstants.TypeRequest, (transaction) => +{ + transaction.Context.Request = new Request(myRequestMethod, myRequestUri); + + // ... code executing the request + + transaction.Context.Response = + new Response { StatusCode = myStatusCode, Finished = wasFinished }; +}); +``` + + +## Span API [api-span] + +A span contains information about a specific code path, executed as part of a transaction. + +If for example a database query happens within a recorded transaction, a span representing this database query may be created. In such a case, the name of the span will contain information about the query itself, and the type will hold information about the database type. + + +#### `ISpan StartSpan(string name, string type, string subType = null, string action = null)` [api-span-create-span] + +Start and return a new custom span as a child of the given span. Very similar to the [`ISpan StartSpan(string name, string type, string subType = null, string action = null)`](#api-transaction-create-span) method on `ITransaction`, but in this case the parent of the newly created span is a span itself. + +It is important to call [`void End()`](#api-span-end) when the span has ended or to use the [`CaptureSpan`](#convenient-capture-span) method. A best practice is to use the span in a try-catch-finally block. + +Example: + +```csharp +ISpan childSpan = parentSpan.StartSpan("Select FROM customer", + ApiConstants.TypeDb, ApiConstants.SubtypeMssql, ApiConstants.ActionQuery); +try +{ + //execute db query +} +catch(Exception e) +{ + childSpan?.CaptureException(e); + throw; +} +finally +{ + childSpan?.End(); +} +``` + + +#### `void SetLabel(string key, T value)` [1.7.0] [api-span-set-label] + +A flat mapping of user-defined labels with string, number or boolean values. + +::::{note} +In version 6.x, labels are stored under `context.tags` in Elasticsearch. As of version 7.x, they are stored as `labels` to comply with the [Elastic Common Schema (ECS)](https://github.com/elastic/ecs). +:::: + + +::::{note} +The labels are indexed in Elasticsearch so that they are searchable and aggregatable. By all means, you should avoid that user specified data, like URL parameters, is used as a tag key as it can lead to mapping explosions. +:::: + + +```csharp +span.SetLabel("stringSample", "bar"); +span.SetLabel("boolSample", true); +span.SetLabel("intSample", 42); +``` + +* `String key`: The tag key +* `String|Number|bool value`: The tag value + + +#### `T TryGetLabel(string key, out T value)` [1.7.1] [api-span-try-get-label] + +Returns the span’s label in the `value` out parameter. If the `key` does not exist, this method returns false. Labels can be added with the [SetLabel](#api-span-set-label) method. + +```csharp +if(span.TryGetLabel("foo", out var myLabel)) + Console.WriteLine(myLabel); +``` + + +#### `Dictionary Labels` [api-span-tags] + +::::{warning} +This property is obsolete and will be be removed in a future version. Use the [`void SetLabel()`](#api-span-set-label) method instead, which allows setting labels of string, boolean and number. This property remains for now in order to not break binary compatibility, and at serialization time, the values set with `.SetLabel()` are combined with `Labels` to form the set of labels sent to APM server, with values in `Labels` taking precedence. +:::: + + +Similar to [`Dictionary Labels`](#api-transaction-tags) on the [Transaction API](#api-transaction): A flat mapping of user-defined labels with string values. + +If the key contains any special characters (`.`,`*`, `"`), they will be replaced with underscores. For example `a.b` will be stored as `a_b`. + +::::{tip} +Before using custom labels, ensure you understand the different types of [metadata](docs-content://solutions/observability/apps/metadata.md) that are available. +:::: + + +::::{warning} +Avoid defining too many user-specified labels. Defining too many unique fields in an index is a condition that can lead to a [mapping explosion](docs-content://manage-data/data-store/mapping.md#mapping-limit-settings). +:::: + + +```csharp +transaction.CaptureSpan(SpanName, SpanType, +span => + { + span.Labels["foo"] = "bar"; + //application code that is captured as a span + }); +``` + + +#### `void CaptureException(Exception e)` [api-span-capture-exception] + +Captures an exception and reports it to the APM server. + + +#### `void CaptureError(string message, string culprit, StackFrame[] frames)` [api-span-capture-error] + +Captures a custom error and reports it to the APM server. + +This method is typically used when you want to report an error, but you don’t have an `Exception` instance. + + +#### `void CaptureErrorLog(ErrorLog errorLog, string parentId = null, Exception exception = null);` [api-span-capture-error-log] + +Captures a custom error and reports it to the APM server with a log attached to it. + +This method is typically used when you already log errors in your code and you want to attach this error to an APM transaction. The log will show up on the APM UI as part of the error and it will be correlated to the transaction of the given span. + + +#### `void End()` [api-span-end] + +Ends the span and schedules it to be reported to the APM Server. + +It is illegal to call any methods on a span instance which has already ended. + + +#### `Context` [api-span-context] + +You can attach additional context to manually captured spans. + +If you use a database library for which agent doesn’t capture spans automatically (see [Data access technologies](/reference/supported-technologies.md#supported-data-access-technologies)), you can add context related to the captured database operation by setting span’s `Context.Db` property. For example: + +```csharp +Agent.Tracer.CurrentTransaction.CaptureSpan("MyDbWrite", ApiConstants.TypeDb, (span) => +{ + span.Context.Db = new Database + { Statement = myDbStatement, Type = myDbType, Instance = myDbInstance }; + + // ... code executing the database operation +}); +``` + +If you use an HTTP library for which agent doesn’t capture spans automatically (see [Networking client-side technologies](/reference/supported-technologies.md#supported-networking-client-side-technologies)), you can add context related to the captured HTTP operation by setting span’s `Context.Http` property. For example: + +```csharp +Agent.Tracer.CurrentTransaction.CaptureSpan("MyHttpOperation", ApiConstants.TypeExternal, (span) => +{ + span.Context.Http = new Http + { Url = myUrl, Method = myMethod }; + + // ... code executing the HTTP operation + + span.Context.Http.StatusCode = myStatusCode; +}); +``` + + +#### `CaptureSpan` [convenient-span-capture-span] + +This is a convenient method which starts and ends a child span on the given span and captures unhandled exceptions. + +Very similar to the [`CaptureSpan`](#convenient-capture-span) method on `ITransaction`, but in this case the parent of the newly created span is a span itself. + +It has 3 required parameters: + +* `name`: The name of the span +* `type` The type of the span +* One of the following types which references the code that you want to capture as a transaction: + + * `Action` + * `Action` + * `Func` + * `Func` + * `Func` + * `Func` + * `Func>` + * `Func>` + + +and 2 optional parameters: + +* `supType`: The subtype of the span +* `action`: The action of the span + +The following code is the equivalent of the previous example from the [`ISpan StartSpan(string name, string type, string subType = null, string action = null)`](#api-span-create-span) section with the convenient API. It automatically starts and ends the span and reports unhandled exceptions. The `s` parameter gives you access to the `ISpan` instance which represents the span that you just created. + +```csharp +span.CaptureSpan("SampleSpan", ApiConstants.TypeDb, (s) => +{ + //execute db query +}, ApiConstants.SubtypeMssql, ApiConstants.ActionQuery); +``` + +Similar to the [`CaptureTransaction`](#convenient-capture-transaction) API, this method also supports `async` methods with the `Func` overloads. + +::::{note} +The duration of the span will be the timespan between the first and the last line of the `async` lambda expression. +:::: + + +This example shows you how to track an `async` code block that returns a result (`Task`) as a span: + +```csharp +var asyncResult = await span.CaptureSpan("Select FROM customer", ApiConstants.TypeDb, async(s) => +{ + //application code that is captured as a span + await Task.Delay(500); //sample async code + return 42; +}); +``` + +::::{note} +Return value of [`CaptureSpan`](#convenient-capture-span) method overloads that accept Task (or Task) is the same Task (or Task) instance as the one passed as the argument so if your application should continue only after the task completes you have to call [`CaptureSpan`](#convenient-capture-span) with `await` keyword. +:::: + + +::::{note} +Code samples above use `Elastic.Apm.Agent.Tracer.CurrentTransaction`. In production code you should make sure the `CurrentTransaction` is not `null`. +:::: + + + +## Filter API ([1.5]) [filter-api] + +Use `Agent.AddFilter(filter)` to supply a filter callback. + +Each filter callback will be called just before data is sent to the APM Server. This allows you to manipulate the data being sent, like to remove sensitive information such as passwords. + +Each filter callback is called in the order they are added and will receive a payload object containing the data about to be sent to the APM Server as the only argument. + +The filter callback is synchronous and should return the manipulated payload object. If a filter callback doesn’t return any value or returns a falsy value, the remaining filter callback will not be called and the payload will not be sent to the APM Server. + +There are 3 overloads of the `Agent.AddFilter` method with the following arguments: + +* `Func`: A filter called for every transaction. +* `Func`: A filter called for every span. +* `Func`: A filter called for every error. + +Below are some usage examples of the Agent.AddFilter method. + +Drop all spans for a specific database: + +```csharp +Agent.AddFilter((ISpan span) => +{ + if (span.Context?.Db?.Instance == "VerySecretDb") + return null; + return span; +}); +``` + +Hide some data: + +```csharp +Agent.AddFilter((ITransaction transaction) => +{ + transaction.Context.Request.Url.Protocol = "[HIDDEN]"; + return transaction; +}); +``` + diff --git a/docs/reference/serilog.md b/docs/reference/serilog.md new file mode 100644 index 000000000..1e9b6f3e9 --- /dev/null +++ b/docs/reference/serilog.md @@ -0,0 +1,43 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/serilog.html +--- + +# Serilog [serilog] + +We offer a [Serilog Enricher](https://github.com/serilog/serilog/wiki/Enrichment) that adds the trace id to every log line that is created during an active trace. + +The enricher lives in the [Elastic.Apm.SerilogEnricher](https://www.nuget.org/packages/Elastic.Apm.SerilogEnricher) NuGet package. + +You can enable it when you configure your Serilog logger: + +```csharp +var logger = new LoggerConfiguration() + .Enrich.WithElasticApmCorrelationInfo() + .WriteTo.Console(outputTemplate: "[{ElasticApmTraceId} {ElasticApmTransactionId} {Message:lj} {NewLine}{Exception}") + .CreateLogger(); +``` + +In the code snippet above `.Enrich.WithElasticApmCorrelationInfo()` enables the enricher, which will set 2 properties for log lines that are created during a transaction: + +* ElasticApmTransactionId +* ElasticApmTraceId + +As you can see, in the `outputTemplate` of the Console sink these two properties are printed. Of course they can be used with any other sink. + +If you want to send your logs directly to Elasticsearch you can use the [Serilog.Sinks.ElasticSearch](https://www.nuget.org/packages/Serilog.Sinks.Elasticsearch) package. Furthermore, you can pass the `EcsTextFormatter` from the [Elastic.CommonSchema.Serilog](https://www.nuget.org/packages/Elastic.CommonSchema.Serilog) package to the Elasticsearch sink, which formats all your logs according to Elastic Common Schema (ECS) and it makes sure that the trace id ends up in the correct field. + +Once you added the two packages mentioned above, you can configure your logger like this: + +```csharp +Log.Logger = new LoggerConfiguration() +.Enrich.WithElasticApmCorrelationInfo() +.WriteTo.Elasticsearch(new ElasticsearchSinkOptions(new Uri("http://localhost:9200")) +{ + CustomFormatter = new EcsTextFormatter() +}) +.CreateLogger(); +``` + +With this setup the application will send all the logs automatically to Elasticsearch and you will be able to jump from traces to logs and from logs to traces. + diff --git a/docs/reference/set-up-apm-net-agent.md b/docs/reference/set-up-apm-net-agent.md new file mode 100644 index 000000000..5249b44df --- /dev/null +++ b/docs/reference/set-up-apm-net-agent.md @@ -0,0 +1,27 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/setup.html +--- + +# Set up the APM .NET agent [setup] + +The .NET agent can be added to an application in three different ways + +Profiler runtime instrumentation +: The agent supports auto instrumentation without any code change and without any recompilation of your projects. See [Profiler Auto instrumentation](/reference/setup-auto-instrumentation.md). + +NuGet packages +: The agent ships as a set of [NuGet packages](/reference/nuget-packages.md) available on [nuget.org](https://nuget.org). You can add the Agent and specific instrumentations to a .NET application by referencing one or more of these packages and following the package documentation. + +Host startup hook +: On **.NET Core 3.0+ or .NET 5+**, the agent supports auto instrumentation without any code change and without any recompilation of your projects. See [Zero code change setup on .NET Core](/reference/setup-dotnet-net-core.md#zero-code-change-setup) for more details. + + +## Get started [_get_started] + +* [Profiler Auto instrumentation](/reference/setup-auto-instrumentation.md) +* [ASP.NET Core](/reference/setup-asp-net-core.md) +* [.NET Core and .NET 5+](/reference/setup-dotnet-net-core.md) +* [ASP.NET](/reference/setup-asp-dot-net.md) +* [Azure Functions](/reference/setup-azure-functions.md) +* [Manual instrumentation](/reference/setup-general.md) diff --git a/docs/reference/setup-asp-dot-net.md b/docs/reference/setup-asp-dot-net.md new file mode 100644 index 000000000..c4a886c4b --- /dev/null +++ b/docs/reference/setup-asp-dot-net.md @@ -0,0 +1,93 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/setup-asp-dot-net.html +--- + +# ASP.NET [setup-asp-dot-net] + + +## Quick start [_quick_start_4] + +To enable auto instrumentation for ASP.NET (Full .NET Framework), you need to install the `Elastic.Apm.AspNetFullFramework` package, add a reference to the package in your `web.config` file, and then compile and deploy your application. + +1. Ensure you have access to the application source code and install the [`Elastic.Apm.AspNetFullFramework`](https://www.nuget.org/packages/Elastic.Apm.AspNetFullFramework) package. +2. Reference the `Elastic.Apm.AspNetFullFramework` in your application’s `web.config` file by adding the `ElasticApmModule` IIS module: + + ```xml + + + + + + + + + ``` + + ::::{note} + There are two available configuration sources. To learn more, see [Configuration on ASP.NET](/reference/configuration-on-asp-net.md). + :::: + + + By default, the agent creates transactions for all HTTP requests, including static content: .html pages, images, etc. + + To create transactions only for HTTP requests with dynamic content, such as `.aspx` pages, add the `managedHandler` preCondition to your `web.config` file: + + ```xml + + + + + + + + + ``` + + ::::{note} + To learn more about adding modules, see the [Microsoft docs](https://docs.microsoft.com/en-us/iis/configuration/system.webserver/modules/add). + :::: + + +::::{note} +Our IIS module requires: + +* IIS 7 or later +* Application pool’s pipeline mode has to be set to integrated (default for IIS 7 and up) +* The deployed .NET application must NOT run under quirks mode. This makes `LegacyAspNetSynchronizationContext` the async context handler and can break `HttpContext.Items` correctly restoring when async code introduces a thread switch. + +:::: + + +1. Recompile your application and deploy it. + + The `ElasticApmModule` instantiates the APM agent on the first initialization. However, there may be some scenarios where you want to control the agent instantiation, such as configuring filters in the application start. + + To do so, the `ElasticApmModule` exposes a `CreateAgentComponents()` method that returns agent components configured to work with ASP.NET Full Framework, which can then instantiate the agent. + + For example, you can add transaction filters to the agent in the application start: + + ```csharp + public class MvcApplication : HttpApplication + { + protected void Application_Start() + { + // other application startup e.g. RouteConfig, etc. + + // set up agent with components + var agentComponents = ElasticApmModule.CreateAgentComponents(); + Agent.Setup(agentComponents); + + // add transaction filter + Agent.AddFilter((ITransaction t) => + { + t.SetLabel("foo", "bar"); + return t; + }); + } + } + ``` + + Now, the `ElasticApmModule` will use the instantiated instance of the APM agent upon initialization. + + diff --git a/docs/reference/setup-asp-net-core.md b/docs/reference/setup-asp-net-core.md new file mode 100644 index 000000000..3ee96f92f --- /dev/null +++ b/docs/reference/setup-asp-net-core.md @@ -0,0 +1,46 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/setup-asp-net-core.html +--- + +# ASP.NET Core [setup-asp-net-core] + + +## Quick start [_quick_start_2] + +For ASP.NET Core, once you reference the [`Elastic.Apm.NetCoreAll`](https://www.nuget.org/packages/Elastic.Apm.NetCoreAll) package, you can enable auto instrumentation by calling the `AddAllElasticApm()` extension method on the `IServiceCollection` in the `Program.cs` file. + +::::{note} +The following code sample assumes the instrumentation of a ASP.NET Core 8 application, using [top-level statements](https://learn.microsoft.com/en-us/dotnet/csharp/tutorials/top-level-statements). + +:::: + + +```csharp +var builder = WebApplication.CreateBuilder(args); + +builder.Services.AddAllElasticApm(); + +var app = builder.Build(); + +// Configure the HTTP request pipeline. + +app.Run(); +``` + +With this you enable every agent component including ASP.NET Core tracing, monitoring of outgoing HTTP request, Entity Framework Core database tracing, etc. + +In case you only reference the [`Elastic.Apm.AspNetCore`](https://www.nuget.org/packages/Elastic.Apm.AspNetCore) package, you won’t find the `AddAllElasticApm`. Instead you need to use the `AddElasticApmForAspNetCore()` method. This method turns on ASP.NET Core tracing, and gives you the opportunity to manually turn on other components. By default it will only trace ASP.NET Core requests - No HTTP request tracing, database call tracing or any other tracing component will be turned on. + +In case you would like to turn on specific tracing components you can pass those to the `AddElasticApm` method. + +For example: + +```csharp +builder.Services.AddElasticApm( + new HttpDiagnosticsSubscriber(), /* Enable tracing of outgoing HTTP requests */ + new EfCoreDiagnosticsSubscriber()); /* Enable tracing of database calls through EF Core*/ +``` + +In case you only want to use the [*Public API*](/reference/public-api.md), you don’t need to do any initialization, you can simply start using the API and the agent will send the data to the APM Server. + diff --git a/docs/reference/setup-auto-instrumentation.md b/docs/reference/setup-auto-instrumentation.md new file mode 100644 index 000000000..6c49b6581 --- /dev/null +++ b/docs/reference/setup-auto-instrumentation.md @@ -0,0 +1,428 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/setup-auto-instrumentation.html +--- + +# Profiler Auto instrumentation [setup-auto-instrumentation] + + +### Quick start [_quick_start] + +The agent can automatically instrument .NET Framework, .NET Core, and .NET applications using the [.NET CLR Profiling APIs](https://docs.microsoft.com/en-us/dotnet/framework/unmanaged-api/profiling/profiling-overview#the-profiling-api). The Profiling APIs provide a way to instrument an application or dependency code without code changes. + +This approach works with the following + +| | | +| --- | --- | +| | **Operating system** | +| **Architecture*** | ***Windows*** | ***Linux** ** | +| x64 | .NET Framework 4.6.2+*
.NET Core 2.1+
.NET 5+ | .NET Core 2.1+
.NET 5+ | + +** Due to binding issues introduced by Microsoft, we recommend at least .NET Framework 4.7.2 for best compatibility.* + +*** Minimum GLIBC version 2.14.* + +::::{note} +The profiler-based agent only supports 64-bit applications. 32-bit applications aren’t supported. +:::: + + +::::{note} +The profiler-based agent does not currently support ARM. +:::: + + +It instruments the following assemblies: + +| Integration name | NuGet package version(s) | Assembly version(s) | +| --- | --- | --- | +| AdoNet | part of .NET | System.Data 4.0.0 - 4.*.* | +| part of .NET | System.Data.Common 4.0.0 - 5.*.* | +| AspNet | part of .NET Framework | System.Web 4.0.0 - 4.*.* | +| Kafka | [Confluent.Kafka 1.4.0 - 1.*.*](https://www.nuget.org/packages/Confluent.Kafka) | Confluent.Kafka 1.4.0 - 1.*.* | +| MySqlCommand | [MySql.Data 6.7.0 - 8.*.*](https://www.nuget.org/packages/MySql.Data) | MySql.Data 6.7.0 - 8.*.* | +| NpgsqlCommand | [Npgsql 4.0.0 - 7.*.*](https://www.nuget.org/packages/Npgsql) | Npgsql 4.0.0 - 7.*.* | +| OracleCommand | [Oracle.ManagedDataAccess 12.2.1100 - 21.*.*](https://www.nuget.org/packages/Oracle.ManagedDataAccess) | Oracle.ManagedDataAccess 4.122.0 - 4.122.* | +| [Oracle.ManagedDataAccess.Core 2.0.0 - 3.*.*](https://www.nuget.org/packages/Oracle.ManagedDataAccess.Core) | Oracle.ManagedDataAccess 2.0.0 - 3.*.* | +| RabbitMQ | [RabbitMQ.Client 3.6.9 - 6.*.*](https://www.nuget.org/packages/RabbitMQ.Client) | RabbitMQ.Client 3.6.9 - 6.*.* | +| SqlCommand | part of .NET | System.Data 4.0.0 - 4.*.* | +| [System.Data.SqlClient 4.0.0 - 4.*.*](https://www.nuget.org/packages/System.Data.SqlClient) | System.Data.SqlClient 4.0.0 - 4.*.* | +| [Microsoft.Data.SqlClient 1.0.0 - 5.*.*](https://www.nuget.org/packages/Microsoft.Data.SqlClient) | Microsoft.Data.SqlClient 1.0.0 - 5.*.* | +| SqliteCommand | [Microsoft.Data.Sqlite 2.0.0 - 7.*.*](https://www.nuget.org/packages/Microsoft.Data.Sqlite) | Microsoft.Data.Sqlite 2.0.0 - 7.*.* | +| [System.Data.SQLite 1.0.0 - 2.*.*](https://www.nuget.org/packages/System.Data.SQLite) | System.Data.SQLite 1.0.0 - 2.*.* | + +::::{important} +**The .NET CLR Profiling API allows only one profiler to be attached to a .NET process**. In light of this limitation, only one solution that uses the .NET CLR profiling API should be used by an application. + +Auto instrumentation using the .NET CLR Profiling API can be used in conjunction with + +* the [Public API](/reference/public-api.md) to perform manual instrumentation. +* NuGet packages that perform instrumentation using a `IDiagnosticsSubscriber` to subscribe to diagnostic events. + +The version number of NuGet packages referenced by a project instrumented with a profiler must be the same as the version number of profiler zip file used. + +:::: + + + +### General steps [_general_steps] + +The general steps in configuring profiler auto instrumentation are as follows; See [Instrumenting containers and services](#instrumenting-containers-and-services) for configuration for common deployment environments. + +1. Download the `elastic_apm_profiler_.zip` file from the [Releases](https://github.com/elastic/apm-agent-dotnet/releases) page of the .NET APM Agent GitHub repository, where `` is the version number to download. You can find the file under Assets. +2. Unzip the zip file into a folder on the host that is hosting the application to instrument. +3. Configure the following environment variables: + + ```sh + set COR_ENABLE_PROFILING = "1" + set COR_PROFILER = "{FA65FE15-F085-4681-9B20-95E04F6C03CC}" + set COR_PROFILER_PATH = "\elastic_apm_profiler.dll" <1> + set ELASTIC_APM_PROFILER_HOME = "" + set ELASTIC_APM_PROFILER_INTEGRATIONS = "\integrations.yml" + set ELASTIC_APM_SERVER_URL = "" <2> + set ELASTIC_APM_SECRET_TOKEN = "" <3> + ``` + + 1. `` is the directory to which the zip file was unzipped in step 2. + 2. The URL of the APM server intake to which traces and metrics should be sent. + 3. The [secret token](docs-content://solutions/observability/apps/secret-token.md) used by the APM Agent to authenticate with APM server. + + + ```sh + set CORECLR_ENABLE_PROFILING = "1" + set CORECLR_PROFILER = "{FA65FE15-F085-4681-9B20-95E04F6C03CC}" + set CORECLR_PROFILER_PATH = "\elastic_apm_profiler.dll" <1> + set ELASTIC_APM_PROFILER_HOME = "" + set ELASTIC_APM_PROFILER_INTEGRATIONS = "\integrations.yml" + set ELASTIC_APM_SERVER_URL = "" <2> + set ELASTIC_APM_SECRET_TOKEN = "" <3> + ``` + + 1. `` is the directory to which the zip file was unzipped in step 2. + 2. The URL of the APM server intake to which traces and metrics should be sent. + 3. The [secret token](docs-content://solutions/observability/apps/secret-token.md) used by the APM Agent to authenticate with APM server. + + + ```sh + export CORECLR_ENABLE_PROFILING=1 + export CORECLR_PROFILER={FA65FE15-F085-4681-9B20-95E04F6C03CC} + export CORECLR_PROFILER_PATH="/libelastic_apm_profiler.so" <1> + export ELASTIC_APM_PROFILER_HOME="" + export ELASTIC_APM_PROFILER_INTEGRATIONS="/integrations.yml" + export ELASTIC_APM_SERVER_URL = "" <2> + export ELASTIC_APM_SECRET_TOKEN = "" <3> + ``` + + 1. `` is the directory to which the zip file was unzipped in step 2. + 2. The URL of the APM server intake to which traces and metrics should be sent. + 3. The [secret token](docs-content://solutions/observability/apps/secret-token.md) used by the APM Agent to authenticate with APM server. + + +Ensure you start your application in a context where the set environment variables are visible. + +With this setup, the .NET runtime loads Elastic’s CLR profiler into the .NET process, which loads and instantiates the APM agent early in application startup. The profiler monitors methods of interest and injects code to instrument their execution. + + +## Instrumenting containers and services [instrumenting-containers-and-services] + +Using global environment variables causes profiler auto instrumentation to be loaded for **any** .NET process started on the host. Often, the environment variables should be set only for specific services or containers. The following sections demonstrate how to configure common containers and services. + + +### Docker containers [_docker_containers] + +A build image containing the files for profiler auto instrumentation can be used as part of a [multi-stage build](https://docs.docker.com/develop/develop-images/multistage-build/) + +```sh +ARG AGENT_VERSION= <1> + +FROM alpine:latest AS build +ARG AGENT_VERSION +WORKDIR /source + +# install unzip +RUN apk update && apk add zip curl + +# pull down the zip file based on ${AGENT_VERSION} ARG and unzip +RUN curl -L -o elastic_apm_profiler_${AGENT_VERSION}.zip https://github.com/elastic/apm-agent-dotnet/releases/download/v${AGENT_VERSION}/elastic_apm_profiler_${AGENT_VERSION}.zip && \ + unzip elastic_apm_profiler_${AGENT_VERSION}.zip -d /elastic_apm_profiler_${AGENT_VERSION} +``` + +1. Replace `` with the newest release version number for the profiler zip file to be downloaded (e.g. ARG AGENT_VERSION=1.26.0). + + +The files can then be copied into a subsequent stage + +```sh +COPY --from=build /elastic_apm_profiler_${AGENT_VERSION} /elastic_apm_profiler +``` + +Environment variables can be added to a Dockerfile to configure profiler auto instrumentation + +```sh +ENV CORECLR_ENABLE_PROFILING=1 +ENV CORECLR_PROFILER={FA65FE15-F085-4681-9B20-95E04F6C03CC} +ENV CORECLR_PROFILER_PATH=/elastic_apm_profiler/libelastic_apm_profiler.so +ENV ELASTIC_APM_PROFILER_HOME=/elastic_apm_profiler +ENV ELASTIC_APM_PROFILER_INTEGRATIONS=/elastic_apm_profiler/integrations.yml + +ENTRYPOINT ["dotnet", "your-application.dll"] +``` + +::::{important} +You should also consider how to securely provide the the APM server URL and secret token as environment variables when you run your container. It is not recommended to include the secret token in the image as it may be accidently exposed. + +:::: + + + +### Windows services [_windows_services] + +Environment variables can be added to specific Windows services by adding an entry to the Windows registry. Using PowerShell + +```powershell +$environment = [string[]]@( + "COR_ENABLE_PROFILING=1", + "COR_PROFILER={FA65FE15-F085-4681-9B20-95E04F6C03CC}", + "COR_PROFILER_PATH=\elastic_apm_profiler.dll", + "ELASTIC_APM_PROFILER_HOME=", + "ELASTIC_APM_PROFILER_INTEGRATIONS=\integrations.yml" + "ELASTIC_APM_SERVER_URL=" + "ELASTIC_APM_SECRET_TOKEN=") + +Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\ -Name Environment -Value $environment +``` + +```powershell +$environment = [string[]]@( + "CORECLR_ENABLE_PROFILING=1", + "CORECLR_PROFILER={FA65FE15-F085-4681-9B20-95E04F6C03CC}", + "CORECLR_PROFILER_PATH=\elastic_apm_profiler.dll", <1> + "ELASTIC_APM_PROFILER_HOME=", + "ELASTIC_APM_PROFILER_INTEGRATIONS=\integrations.yml" + "ELASTIC_APM_SERVER_URL=" <2> + "ELASTIC_APM_SECRET_TOKEN=") <3> + +Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\ -Name Environment -Value $environment <4> +``` + +1. `` is the directory to which the zip file was unzipped. +2. The URL of the APM server intake to which traces and metrics should be sent. +3. The [secret token](docs-content://solutions/observability/apps/secret-token.md) used by the APM Agent to authenticate with APM server. +4. `` is the name of the Windows service. + + +The service must then be restarted for the change to take effect. With PowerShell + +```powershell +Restart-Service +``` + + +### Internet Information Services (IIS) [_internet_information_services_iis] + +For IIS versions *before* IIS 10, it is **not** possible to set environment variables scoped to a specific application pool, so environment variables need to set globally. + +For IIS 10 *onwards*, environment variables can be set for an application pool using [AppCmd.exe](https://docs.microsoft.com/en-us/iis/get-started/getting-started-with-iis/getting-started-with-appcmdexe). With PowerShell + +```powershell +$appcmd = "$($env:systemroot)\system32\inetsrv\AppCmd.exe" +$appPool = "" <1> +$profilerHomeDir = "" <2> +$environment = @{ + COR_ENABLE_PROFILING = "1" + COR_PROFILER = "{FA65FE15-F085-4681-9B20-95E04F6C03CC}" + COR_PROFILER_PATH = "$profilerHomeDir\elastic_apm_profiler.dll" + ELASTIC_APM_PROFILER_HOME = "$profilerHomeDir" + ELASTIC_APM_PROFILER_INTEGRATIONS = "$profilerHomeDir\integrations.yml" + COMPlus_LoaderOptimization = "1" <3> + ELASTIC_APM_SERVER_URL = "" <4> + ELASTIC_APM_SECRET_TOKEN = "" <5> +} + +$environment.Keys | ForEach-Object { + & $appcmd set config -section:system.applicationHost/applicationPools /+"[name='$appPool'].environmentVariables.[name='$_',value='$($environment[$_])']" +} +``` + +1. `` is the name of the Application Pool your application uses. For example, `IIS APPPOOL\DefaultAppPool` +2. `` is the full path to the directory in which the zip file was unzipped +3. Forces assemblies **not** to be loaded domain-neutral. There is currently a limitation where Profiler auto-instrumentation cannot instrument assemblies when they are loaded domain-neutral. This limitation is expected to be removed in future, but for now, can be worked around by setting this environment variable. See the [Microsoft documentation for further details](https://docs.microsoft.com/en-us/dotnet/framework/app-domains/application-domains#the-complus_loaderoptimization-environment-variable). +4. The URL of the APM server intake to which traces and metrics should be sent. +5. The [secret token](docs-content://solutions/observability/apps/secret-token.md) used by the APM Agent to authenticate with APM server. + + +```powershell +$appcmd = "$($env:systemroot)\system32\inetsrv\AppCmd.exe" +$appPool = "" <1> +$profilerHomeDir = "" <2> +$environment = @{ + CORECLR_ENABLE_PROFILING = "1" + CORECLR_PROFILER = "{FA65FE15-F085-4681-9B20-95E04F6C03CC}" + CORECLR_PROFILER_PATH = "$profilerHomeDir\elastic_apm_profiler.dll" + ELASTIC_APM_PROFILER_HOME = "$profilerHomeDir" + ELASTIC_APM_PROFILER_INTEGRATIONS = "$profilerHomeDir\integrations.yml" + ELASTIC_APM_SERVER_URL = "" <3> + ELASTIC_APM_SECRET_TOKEN = "" <4> +} + +$environment.Keys | ForEach-Object { + & $appcmd set config -section:system.applicationHost/applicationPools /+"[name='$appPool'].environmentVariables.[name='$_',value='$($environment[$_])']" +} +``` + +1. `` is the name of the Application Pool your application uses. For example, `IIS APPPOOL\DefaultAppPool`. +2. `` is the full path to the directory in which the zip file was unzipped. +3. The URL of the APM server intake to which traces and metrics should be sent. +4. The [secret token](docs-content://solutions/observability/apps/secret-token.md) used by the APM Agent to authenticate with APM server. + + +::::{important} +Ensure that the location of the `` is accessible and executable to the [Identity account under which the Application Pool runs](https://docs.microsoft.com/en-us/iis/manage/configuring-security/application-pool-identities). + +:::: + + +Once environment variables have been set, stop and start IIS so that applications hosted in IIS will see the new environment variables. + +```sh +net stop /y was +net start w3svc +``` + + +### systemd / systemctl [_systemd_systemctl] + +Environment variables can be added to specific services run with systemd by creating an environment.env file containing the following + +```sh +CORECLR_ENABLE_PROFILING=1 +CORECLR_PROFILER={FA65FE15-F085-4681-9B20-95E04F6C03CC} +CORECLR_PROFILER_PATH=//libelastic_apm_profiler.so <1> +ELASTIC_APM_PROFILER_HOME=/ +ELASTIC_APM_PROFILER_INTEGRATIONS=//integrations.yml +ELASTIC_APM_SERVER_URL= <2> +ELASTIC_APM_SECRET_TOKEN= <3> +``` + +1. `` is the directory to which the zip file was unzipped. +2. The URL of the APM server intake to which traces and metrics should be sent. +3. The [secret token](docs-content://solutions/observability/apps/secret-token.md) used by the APM Agent to authenticate with APM server. + + +Then adding an [`EnvironmentFile`](https://www.freedesktop.org/software/systemd/man/systemd.service.md#Command%20lines) entry to the service’s configuration file that references the path to the environment.env file + +```sh +[Service] +EnvironmentFile=/path/to/environment.env +ExecStart= <1> +``` + +1. the command that starts your service + + +After adding the `EnvironmentFile` entry, restart the service. + +```sh +systemctl reload-or-restart +``` + + +## Profiler environment variables [profiler-configuration] + +The profiler auto instrumentation has its own set of environment variables to manage the instrumentation. These are used in addition to [agent configuration](/reference/configuration.md) through environment variables. + +`ELASTIC_APM_PROFILER_HOME` +: The home directory of the profiler auto instrumentation. The home directory typically contains: + + * platform specific profiler assemblies + * a directory for each compatible target framework, where each directory contains supporting managed assemblies for auto instrumentation. + * an integrations.yml file that determines which methods to target for auto instrumentation + + +`ELASTIC_APM_PROFILER_INTEGRATIONS` *(optional)* +: The path to the integrations.yml file that determines which methods to target for auto instrumentation. If not specified, the profiler will assume an integrations.yml exists in the home directory specified by `ELASTIC_APM_PROFILER_HOME` environment variable. + +`ELASTIC_APM_PROFILER_EXCLUDE_INTEGRATIONS` *(optional)* +: A semi-colon separated list of integrations to exclude from auto-instrumentation. Valid values are those defined in the `Integration name` column in the integrations table above. + +`ELASTIC_APM_PROFILER_EXCLUDE_PROCESSES` *(optional)* +: A semi-colon separated list of process names to exclude from auto-instrumentation. For example, `dotnet.exe;powershell.exe`. Can be used in scenarios where profiler environment variables have a global scope that would end up auto-instrumenting applications that should not be. + +The following processes are **always** excluded from profiling by default. + +* powershell.exe +* ServerManager.exe +* ReportingServicesService.exe +* RSHostingService.exe +* RSMananagement.exe +* RSPortal.exe +* RSConfigTool.exe + + `ELASTIC_APM_PROFILER_EXCLUDE_SERVICE_NAMES` *(optional)* + : A semi-colon separated list of APM service names to exclude from auto-instrumentation. Values defined are checked against the value of [`ELASTIC_APM_SERVICE_NAME`](/reference/config-core.md#config-service-name) environment variable. + + +The following service names are **always** excluded from profiling by default. + +* SQLServerReportingServices + + `ELASTIC_OTEL_LOG_LEVEL` *(optional)* + : The log level at which the profiler should log. Valid values are + +* trace +* debug +* info +* warn +* error +* none + +The default value is `warn`. More verbose log levels like `trace` and `debug` can affect the runtime performance of profiler auto instrumentation, so are recommended *only* for diagnostics purposes. + +This takes precedence over the now deprecated `ELASTIC_APM_PROFILER_LOG` + +`ELASTIC_OTEL_LOG_DIRECTORY` *(optional)* +: The directory in which to write profiler log files. If unset, defaults to + + * `%PROGRAMDATA%\elastic\apm-agent-dotnet\logs` on Windows + * `/var/log/elastic/apm-agent-dotnet` on Linux + + +If the default directory cannot be written to for some reason, the profiler will try to write log files to a `logs` directory in the home directory specified by `ELASTIC_APM_PROFILER_HOME` environment variable. + +This takes precedence over the now deprecated `ELASTIC_APM_PROFILER_LOG_DIR` + +::::{important} +The user account under which the profiler process runs must have permission to write to the destination log directory. Specifically, ensure that when running on IIS, the [AppPool identity](https://learn.microsoft.com/en-us/iis/manage/configuring-security/application-pool-identities) has write permissions in the target directory. + +:::: + + +`ELASTIC_OTEL_LOG_TARGETS` *(optional)* +: A semi-colon separated list of targets for profiler logs. Valid values are + + * file + * stdout + + +The default value is `file`, which logs to the directory specified by `ELASTIC_APM_PROFILER_LOG_DIR` environment variable. + +This takes precedence over the now deprecated `ELASTIC_APM_PROFILER_LOG_TARGETS` + + +### Troubleshooting [_troubleshooting] + + +#### DLLs are blocked on Windows [windows-blocked-dlls] + +Windows may automatically block downloaded DLL files if it considers them suspicious. + +To unblock a DLL file on Windows, you can do the following: + +* Right-click the DLL file in File Explorer +* Select Properties +* In the General tab, look for the Security section at the bottom +* Select the Unblock check box and click OK + +:::{image} ../images/unblock-profiler-dll.png +:alt: Unblock DLL in Windows file properties +::: diff --git a/docs/reference/setup-azure-cosmosdb.md b/docs/reference/setup-azure-cosmosdb.md new file mode 100644 index 000000000..aab523347 --- /dev/null +++ b/docs/reference/setup-azure-cosmosdb.md @@ -0,0 +1,18 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/setup-azure-cosmosdb.html +--- + +# Azure Cosmos DB [setup-azure-cosmosdb] + + +## Quick start [_quick_start_11] + +Instrumentation can be enabled for Azure Cosmos DB by referencing [`Elastic.Apm.Azure.CosmosDb`](https://www.nuget.org/packages/Elastic.Apm.Azure.CosmosDb) package and subscribing to diagnostic events. + +```csharp +Agent.Subscribe(new AzureCosmosDbDiagnosticsSubscriber()); +``` + +Diagnostic events from `Microsoft.Azure.Cosmos`, `Microsoft.Azure.DocumentDb`, and `Microsoft.Azure.DocumentDb.Core` are captured as DB spans. + diff --git a/docs/reference/setup-azure-functions.md b/docs/reference/setup-azure-functions.md new file mode 100644 index 000000000..26122a0ab --- /dev/null +++ b/docs/reference/setup-azure-functions.md @@ -0,0 +1,103 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/setup-azure-functions.html +--- + +# Azure Functions [setup-azure-functions] + +The .NET APM Agent can trace HTTP triggered function invocations in an [Azure Functions](https://learn.microsoft.com/en-us/azure/azure-functions) app. + + +## Prerequisites [_prerequisites] + +You need an APM Server to send APM data to. Follow the [APM Quick start](docs-content://solutions/observability/apps/get-started-with-apm.md) if you have not set one up yet. You will need your **APM server URL** and an APM server **secret token** (or **API key**) for configuring the APM agent below. + +You will also need an Azure Function app to monitor. If you do not have an existing one, you can follow [this Azure guide](https://learn.microsoft.com/en-us/azure/azure-functions/create-first-function-cli-csharp) to create one. + +You can also take a look at and use this [Azure Functions example app with Elastic APM already integrated](https://github.com/elastic/apm-agent-dotnet/tree/main/test/azure/applications/Elastic.AzureFunctionApp.Isolated). + + +## Azure Functions isolated worker model [_azure_functions_isolated_worker_model] + + +### Step 1: Add the NuGet package [azure-functions-setup] + +Add the `Elastic.Apm.Azure.Functions` NuGet package to your Azure Functions project: + +```bash +dotnet add package Elastic.Apm.Azure.Functions +``` + + +### Step 2: Add the tracing Middleware [_step_2_add_the_tracing_middleware] + +For the APM agent to trace Azure Functions invocations, the `Elastic.Apm.Azure.Functions.ApmMiddleware` must be used in your Azure Functions app. + +```csharp +using Elastic.Apm.Azure.Functions; +using Microsoft.Extensions.Hosting; + +var host = new HostBuilder() + .ConfigureFunctionsWebApplication(builder => + { + builder.UseMiddleware(); + }) + .Build(); + +host.Run(); +``` + + +### Step 3: Configure the APM agent [_step_3_configure_the_apm_agent] + +The APM agent can be configured with environment variables. + +```yaml +ELASTIC_APM_SERVER_URL: +ELASTIC_APM_SECRET_TOKEN: +ELASTIC_APM_ENVIRONMENT: +ELASTIC_APM_SERVICE_NAME: (optional) +``` + +If `ELASTIC_APM_SERVICE_NAME` is not configured, the agent will use a fallback value. + +* **Local development** - The discovered service name (the entry Assembly name) will be used. +* **Azure** - The Function App name (retrieved from the `WEBSITE_SITE_NAME` environment variable) will be used. + +**Configuring in Local development** + +While developing your Function locally, you can configure the agent by providing the environment variables via the `local.settings.json` file. + +For example: + +```json +{ + "IsEncrypted": false, + "Values": { + "AzureWebJobsStorage": "UseDevelopmentStorage=true", + "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated", + "ELASTIC_APM_ENVIRONMENT": "Development", + "ELASTIC_APM_SERVICE_NAME": "MyServiceName", + "ELASTIC_APM_SERVER_URL": "https://my-serverless-project.apm.eu-west-1.aws.elastic.cloud:443", + "ELASTIC_APM_API_KEY": "MySecureApiKeyFromApmServer==" + } +} +``` + +**Configuring in Azure** + +Using environment variables allows you to use [application settings in the Azure Portal](https://learn.microsoft.com/en-us/azure/azure-functions/functions-how-to-use-azure-function-app-settings?tabs=portal#settings), enabling you to update settings without needing to re-deploy code. + +Open *Settings > Environment variables* for your Function App in the Azure Portal and configure the ELASTIC_APM_* variables as required. + +For example: + +:::{image} ../images/azure-functions-configuration.png +:alt: Configuring the APM Agent in the Azure Portal +::: + + +## Limitations [azure-functions-limitations] + +Azure Functions instrumentation currently does *not* collect system metrics in the background because of a concern with unintentionally increasing Azure Functions costs (for Consumption plans). + diff --git a/docs/reference/setup-azure-servicebus.md b/docs/reference/setup-azure-servicebus.md new file mode 100644 index 000000000..b0d503e7a --- /dev/null +++ b/docs/reference/setup-azure-servicebus.md @@ -0,0 +1,36 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/setup-azure-servicebus.html +--- + +# Azure Service Bus [setup-azure-servicebus] + + +## Quick start [_quick_start_12] + +Instrumentation can be enabled for Azure Service Bus by referencing [`Elastic.Apm.Azure.ServiceBus`](https://www.nuget.org/packages/Elastic.Apm.Azure.ServiceBus) package and subscribing to diagnostic events using one of the subscribers: + +1. If the agent is included by referencing the `Elastic.Apm.NetCoreAll` package, the subscribers will be automatically subscribed with the agent, and no further action is required. +2. If you’re using `Microsoft.Azure.ServiceBus`, subscribe `MicrosoftAzureServiceBusDiagnosticsSubscriber` with the agent + + ```csharp + Agent.Subscribe(new MicrosoftAzureServiceBusDiagnosticsSubscriber()); + ``` + +3. If you’re using `Azure.Messaging.ServiceBus`, subscribe `AzureMessagingServiceBusDiagnosticsSubscriber` with the agent + + ```csharp + Agent.Subscribe(new AzureMessagingServiceBusDiagnosticsSubscriber()); + ``` + + +A new transaction is created when + +* one or more messages are received from a queue or topic subscription. +* a message is receive deferred from a queue or topic subscription. + +A new span is created when there is a current transaction, and when + +* one or more messages are sent to a queue or topic. +* one or more messages are scheduled to a queue or a topic. + diff --git a/docs/reference/setup-azure-storage.md b/docs/reference/setup-azure-storage.md new file mode 100644 index 000000000..7ffc9aa48 --- /dev/null +++ b/docs/reference/setup-azure-storage.md @@ -0,0 +1,41 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/setup-azure-storage.html +--- + +# Azure Storage [setup-azure-storage] + + +## Quick start [_quick_start_13] + +Instrumentation can be enabled for Azure Storage by referencing [`Elastic.Apm.Azure.Storage`](https://www.nuget.org/packages/Elastic.Apm.Azure.Storage) package and subscribing to diagnostic events using one of the subscribers: + +* If the agent is included by referencing the `Elastic.Apm.NetCoreAll` package, the subscribers will be automatically subscribed with the agent, and no further action is required. +* If you’re using `Azure.Storage.Blobs`, subscribe `AzureBlobStorageDiagnosticsSubscriber` with the agent + + ```csharp + Agent.Subscribe(new AzureBlobStorageDiagnosticsSubscriber()); + ``` + +* If you’re using `Azure.Storage.Queues`, subscribe `AzureQueueStorageDiagnosticsSubscriber` with the agent + + ```csharp + Agent.Subscribe(new AzureQueueStorageDiagnosticsSubscriber()); + ``` + +* If you’re using `Azure.Storage.Files.Shares`, subscribe `AzureFileShareStorageDiagnosticsSubscriber` with the agent + + ```csharp + Agent.Subscribe(new AzureFileShareStorageDiagnosticsSubscriber()); + ``` + + +For Azure Queue storage, + +* A new transaction is created when one or more messages are received from a queue +* A new span is created when there is a current transaction, and when a message is sent to a queue + +For Azure Blob storage, a new span is created when there is a current transaction and when a request is made to blob storage. + +For Azure File Share storage, a new span is crated when there is a current transaction and when a request is made to file storage. + diff --git a/docs/reference/setup-dotnet-net-core.md b/docs/reference/setup-dotnet-net-core.md new file mode 100644 index 000000000..dea4d5b3b --- /dev/null +++ b/docs/reference/setup-dotnet-net-core.md @@ -0,0 +1,186 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/setup-dotnet-net-core.html +--- + +# .NET Core and .NET 5+ [setup-dotnet-net-core] + + +## Quick start [_quick_start_3] + +In .NET (Core) applications using `Microsoft.Extensions.Hosting`, the agent can be registered on the `IServiceCollection`. This applies to ASP.NET Core and to other .NET applications that depend on the hosting APIs, such as those created using the [worker services](https://learn.microsoft.com/en-us/dotnet/core/extensions/workers) template. + +The simplest way to enable the agent and its instrumentations requires a reference to the [`Elastic.Apm.NetCoreAll`](https://www.nuget.org/packages/Elastic.Apm.NetCoreAll) package. + +```xml + <1> +``` + +1. Replace the `` placeholder with the latest version of the agent available on NuGet. + + +::::{note} +The following code sample assumes the instrumentation of a .NET 8 worker service, using [top-level statements](https://learn.microsoft.com/en-us/dotnet/csharp/tutorials/top-level-statements). + +:::: + + +**Program.cs** + +```csharp +using WorkerServiceSample; + +var builder = Host.CreateApplicationBuilder(args); + +builder.Services.AddHttpClient(); +builder.Services.AddAllElasticApm(); <1> +builder.Services.AddHostedService(); + +var host = builder.Build(); +host.Run(); +``` + +1. Register Elastic APM before registering other IHostedServices to ensure its dependencies are initialized first. + + +When registering services with `AddAllElasticApm()`, an APM agent with all instrumentations is enabled. On ASP.NET Core, it’ll automatically capture incoming requests, database calls through supported technologies, outgoing HTTP requests, etc. + +For other application templates, such as worker services, you must manually instrument your `BackgroundService` to identify one or more units of work that should be captured. + + +## Manual instrumentation using `ITracer` [_manual_instrumentation_using_itracer] + +`AddAllElasticApm` adds an `ITracer` to the Dependency Injection system, which can be used in your code to manually instrument your application, using the [*Public API*](/reference/public-api.md) + +**Worker.cs** + +```csharp +using Elastic.Apm.Api; + +namespace WorkerServiceSample +{ + public class Worker : BackgroundService + { + private readonly IHttpClientFactory _httpClientFactory; + private readonly ITracer _tracer; + + public Worker(IHttpClientFactory httpClientFactory, ITracer tracer) + { + _httpClientFactory = httpClientFactory; + _tracer = tracer; + } + + protected override async Task ExecuteAsync(CancellationToken stoppingToken) + { + while (!stoppingToken.IsCancellationRequested) + { + await _tracer.CaptureTransaction("UnitOfWork", ApiConstants.TypeApp, async () => <1> + { + var client = _httpClientFactory.CreateClient(); + await client.GetAsync("https://www.elastic.co", stoppingToken); + await Task.Delay(5000, stoppingToken); + }); + } + } + } +} +``` + +1. The `CaptureTransaction` method creates a transaction named *UnitOfWork* and type *App*. The lambda passed to it represents the unit of work that should be captured within the context of the transaction. + + +When this application runs, a new transaction will be captured and sent for each while loop iteration. A span named *HTTP GET* within the transaction will be created for the HTTP request to `https://www.elastic.co`. The HTTP span is captured because the NetCoreAll package enables this instrumentation automatically. + + +## Manual instrumentation using OpenTelemetry [_manual_instrumentation_using_opentelemetry] + +As an alternative to using the Elastic APM API by injecting an `ITracer`, you can use the OpenTelemetry API to manually instrument your application. The Elastic APM agent automatically bridges instrumentations created using the OpenTelemetry API, so you can use it to create spans and transactions. In .NET, the [`Activity` API](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/distributed-tracing-instrumentation-walkthroughs) can be used to instrument applications. + +In the case of this sample worker service, we can update the code to prefer the OpenTelemetry API. + +**Worker.cs** + +```csharp +using System.Diagnostics; + +namespace WorkerServiceSample +{ + public class Worker : BackgroundService + { + private readonly IHttpClientFactory _httpClientFactory; + private static readonly ActivitySource ActivitySource = new("MyActivitySource"); <1> + + public Worker(IHttpClientFactory httpClientFactory) + { + _httpClientFactory = httpClientFactory; + } + + protected override async Task ExecuteAsync(CancellationToken stoppingToken) + { + while (!stoppingToken.IsCancellationRequested) + { + using var activity = ActivitySource.StartActivity("UnitOfWork"); <2> + var client = _httpClientFactory.CreateClient(); + await client.GetAsync("https://www.elastic.co", stoppingToken); + await Task.Delay(5000, stoppingToken); + } + } + } +} +``` + +1. Defines an `ActivitySource` for this application from which activities can be created. +2. Starts an `Activity` with the name `UnitOfWork`. As this is `IDisposable`, it will automatically end when each iteration of the `while` block ends. + + + +## Instrumentation modules [_instrumentation_modules] + +The `Elastic.Apm.NetCoreAll` package references every agent component that can be automatically configured. This is usually not a problem, but if you want to keep dependencies minimal, you can instead reference the `Elastic.Apm.Extensions.Hosting` package and register services with `AddElasticApm` method, instead of `AddAllElasticApm`. With this setup you can explicitly control what the agent will listen for. + +The following example only turns on outgoing HTTP monitoring (so, for instance, database and Elasticsearch calls won’t be automatically captured): + +```csharp +using Elastic.Apm.DiagnosticSource; +using WorkerServiceSample; + +var builder = Host.CreateApplicationBuilder(args); + +builder.Services.AddHttpClient(); +builder.Services.AddElasticApm(new HttpDiagnosticsSubscriber()); <1> +builder.Services.AddHostedService(); + +var host = builder.Build(); +host.Run(); +``` + +1. The `HttpDiagnosticsSubscriber` is a diagnostic listener that captures spans for outgoing HTTP requests. + + + +## Zero code change setup on .NET Core and .NET 5+ ([1.7]) [zero-code-change-setup] + +If you can’t or don’t want to reference NuGet packages in your application, you can use the startup hook feature to inject the agent during startup, if your application runs on .NET Core 3.0, .NET Core 3.1 or .NET 5 or newer. + +To configure startup hooks + +1. Download the `ElasticApmAgent_.zip` file from the [Releases](https://github.com/elastic/apm-agent-dotnet/releases) page of the .NET APM Agent GitHub repository. You can find the file under Assets. +2. Unzip the zip file into a folder. +3. Set the `DOTNET_STARTUP_HOOKS` environment variable to point to the `ElasticApmAgentStartupHook.dll` file in the unzipped folder + + ```sh + set DOTNET_STARTUP_HOOKS=\ElasticApmAgentStartupHook.dll <1> + ``` + + 1. `` is the unzipped directory from step 2. + +4. Start your .NET Core application in a context where the `DOTNET_STARTUP_HOOKS` environment variable is visible. + +With this setup, the agent will be injected into the application during startup, enabling every instrumentation feature. Incoming requests will be automatically captured on ASP.NET Core (including gRPC). + +::::{note} +Agent configuration can be controlled through environment variables when using the startup hook feature. + +:::: + + diff --git a/docs/reference/setup-ef-core.md b/docs/reference/setup-ef-core.md new file mode 100644 index 000000000..70849c901 --- /dev/null +++ b/docs/reference/setup-ef-core.md @@ -0,0 +1,24 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/setup-ef-core.html +--- + +# Entity Framework Core [setup-ef-core] + + +## Quick start [_quick_start_5] + +Instrumentation can be enabled for Entity Framework Core by referencing [`Elastic.Apm.EntityFrameworkCore`](https://www.nuget.org/packages/Elastic.Apm.EntityFrameworkCore) package and passing `EfCoreDiagnosticsSubscriber` to the `AddElasticApm` method in case of ASP.NET Core as following + +```csharp +app.Services.AddElasticApm(new EfCoreDiagnosticsSubscriber()); +``` + +or passing `EfCoreDiagnosticsSubscriber` to the `Subscribe` method + +```csharp +Agent.Subscribe(new EfCoreDiagnosticsSubscriber()); +``` + +Instrumentation listens for diagnostic events raised by `Microsoft.EntityFrameworkCore` 2.x+, creating database spans for executed commands. + diff --git a/docs/reference/setup-ef6.md b/docs/reference/setup-ef6.md new file mode 100644 index 000000000..28b0b814a --- /dev/null +++ b/docs/reference/setup-ef6.md @@ -0,0 +1,38 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/setup-ef6.html +--- + +# Entity Framework 6 [setup-ef6] + + +## Quick start [_quick_start_6] + +You can enable auto instrumentation for Entity Framework 6 by referencing the [`Elastic.Apm.EntityFramework6`](https://www.nuget.org/packages/Elastic.Apm.EntityFramework6) package and including the `Ef6Interceptor` interceptor in your application’s `web.config`: + +```xml + + + + + + + + +``` + +As an alternative to registering the interceptor via the configuration, you can register it in the application code: + +```csharp +DbInterception.Add(new Elastic.Apm.EntityFramework6.Ef6Interceptor()); +``` + +For example, in an ASP.NET application, you can place the above call in the `Application_Start` method. + +Instrumentation works with EntityFramework 6.2+ NuGet packages. + +::::{note} +Be careful not to execute `DbInterception.Add` for the same interceptor type more than once, as this will register multiple instances, causing multiple database spans to be captured for every SQL command. +:::: + + diff --git a/docs/reference/setup-elasticsearch.md b/docs/reference/setup-elasticsearch.md new file mode 100644 index 000000000..935343886 --- /dev/null +++ b/docs/reference/setup-elasticsearch.md @@ -0,0 +1,30 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/setup-elasticsearch.html +--- + +# Elasticsearch [setup-elasticsearch] + + +## Quick start [_quick_start_7] + +Instrumentation can be enabled for Elasticsearch when using the official Elasticsearch clients, Elasticsearch.Net and Nest, by referencing [`Elastic.Apm.Elasticsearch`](https://www.nuget.org/packages/Elastic.Apm.Elasticsearch) package and passing `ElasticsearchDiagnosticsSubscriber` to the `AddElasticApm` method in case of ASP.NET Core as following + +```csharp +app.Services.AddElasticApm(new ElasticsearchDiagnosticsSubscriber()); +``` + +or passing `ElasticsearchDiagnosticsSubscriber` to the `Subscribe` method + +```csharp +Agent.Subscribe(new ElasticsearchDiagnosticsSubscriber()); +``` + +Instrumentation listens for activities raised by `Elasticsearch.Net` and `Nest` 7.6.0+, creating spans for executed requests. + +::::{important} +If you’re using `Elasticsearch.Net` and `Nest` 7.10.1 or 7.11.0, upgrade to at least 7.11.1 which fixes a bug in span capturing. + +:::: + + diff --git a/docs/reference/setup-general.md b/docs/reference/setup-general.md new file mode 100644 index 000000000..9adc526ac --- /dev/null +++ b/docs/reference/setup-general.md @@ -0,0 +1,11 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/setup-general.html +--- + +# Other .NET applications [setup-general] + +If you have a .NET application that is not covered in this section, you can still use the agent and instrument your application manually. + +To do this, add the [Elastic.Apm](https://www.nuget.org/packages/Elastic.Apm) package to your application and use the [*Public API*](/reference/public-api.md) to manually create spans and transactions. + diff --git a/docs/reference/setup-grpc.md b/docs/reference/setup-grpc.md new file mode 100644 index 000000000..6a0a4a190 --- /dev/null +++ b/docs/reference/setup-grpc.md @@ -0,0 +1,28 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/setup-grpc.html +--- + +# gRPC [setup-grpc] + + +## Quick start [_quick_start_8] + +Automatic instrumentation for gRPC can be enabled for both client-side and server-side gRPC calls. + +Automatic instrumentation for ASP.NET Core server-side is built in to [NuGet package](/reference/setup-asp-net-core.md) + +Automatic instrumentation can be enabled for the client-side by referencing [`Elastic.Apm.GrpcClient`](https://www.nuget.org/packages/Elastic.Apm.GrpcClient) package and passing `GrpcClientDiagnosticListener` to the `AddElasticApm` method in case of ASP.NET Core + +```csharp +app.Services.AddElasticApm(new GrpcClientDiagnosticListener()); +``` + +or passing `GrpcClientDiagnosticSubscriber` to the `Subscribe` method + +```csharp +Agent.Subscribe(new GrpcClientDiagnosticSubscriber()); +``` + +Diagnostic events from `Grpc.Net.Client` are captured as spans. + diff --git a/docs/reference/setup-mongo-db.md b/docs/reference/setup-mongo-db.md new file mode 100644 index 000000000..c90d0b339 --- /dev/null +++ b/docs/reference/setup-mongo-db.md @@ -0,0 +1,34 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/setup-mongo-db.html +--- + +# MongoDB [setup-mongo-db] + + +## Quick start [_quick_start_14] + +Instrumentation for MongoDB works with the official MongoDb.Driver 2.4.4+ driver packages. A prerequisite for auto instrumentation is to configure the `MongoClient` with `MongoDbEventSubscriber`: + +```csharp +var settings = MongoClientSettings.FromConnectionString(mongoConnectionString); + +settings.ClusterConfigurator = builder => builder.Subscribe(new MongoDbEventSubscriber()); +var mongoClient = new MongoClient(settings); +``` + +Once the above configuration is in place + +* if the agent is included by referencing the `Elastic.Apm.NetCoreAll` package, it will automatically capture calls to MongoDB on every active transaction, and no further action is required. +* you can manually activate auto instrumentation from the `Elastic.Apm.MongoDb` package by calling + +```csharp +Agent.Subscribe(new MongoDbDiagnosticsSubscriber()); +``` + +::::{important} +MongoDB integration is currently supported on .NET Core and newer. Due to MongoDb.Driver assemblies not being strongly named, they cannot be used with Elastic APM’s strongly named assemblies on .NET Framework. + +:::: + + diff --git a/docs/reference/setup-sqlclient.md b/docs/reference/setup-sqlclient.md new file mode 100644 index 000000000..cb087b296 --- /dev/null +++ b/docs/reference/setup-sqlclient.md @@ -0,0 +1,34 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/setup-sqlclient.html +--- + +# SqlClient [setup-sqlclient] + + +## Quick start [_quick_start_9] + +You can enable auto instrumentation for `System.Data.SqlClient` or `Microsoft.Data.SqlClient` by referencing [`Elastic.Apm.SqlClient`](https://www.nuget.org/packages/Elastic.Apm.SqlClient) package and passing `SqlClientDiagnosticSubscriber` to the `AddElasticApm` method in case of ASP.NET Core as it shown in example: + +```csharp +// Enable tracing of outgoing db requests +app.Services.AddElasticApm(new SqlClientDiagnosticSubscriber()); +``` + +or passing `SqlClientDiagnosticSubscriber` to the `Subscribe` method and make sure that the code is called only once, otherwise the same database call could be captured multiple times: + +```csharp +// Enable tracing of outgoing db requests +Agent.Subscribe(new SqlClientDiagnosticSubscriber()); +``` + +::::{note} +Auto instrumentation for `System.Data.SqlClient` is available for both .NET Core and .NET Framework applications, however, support of .NET Framework has one limitation: command text cannot be captured. + +Auto instrumentation for `Microsoft.Data.SqlClient` is available only for .NET Core at the moment. + +As an alternative to using the `Elastic.Apm.SqlClient` package to instrument database calls, see [Profiler Auto instrumentation](/reference/setup-auto-instrumentation.md). + +:::: + + diff --git a/docs/reference/setup-stackexchange-redis.md b/docs/reference/setup-stackexchange-redis.md new file mode 100644 index 000000000..00fe0591b --- /dev/null +++ b/docs/reference/setup-stackexchange-redis.md @@ -0,0 +1,21 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/setup-stackexchange-redis.html +--- + +# StackExchange.Redis [setup-stackexchange-redis] + + +## Quick start [_quick_start_10] + +Instrumentation can be enabled for `StackExchange.Redis` by referencing [`Elastic.Apm.StackExchange.Redis`](https://www.nuget.org/packages/Elastic.Apm.StackExchange.Redis) package and calling the `UseElasticApm()` extension method defined in `Elastic.Apm.StackExchange.Redis`, on `IConnectionMultiplexer` + +```csharp +// using Elastic.Apm.StackExchange.Redis; + +var connection = await ConnectionMultiplexer.ConnectAsync(""); +connection.UseElasticApm(); +``` + +A callback is registered with the `IConnectionMultiplexer` to provide a profiling session for each transaction and span that captures redis commands sent with `IConnectionMultiplexer`. + diff --git a/docs/reference/supported-technologies.md b/docs/reference/supported-technologies.md new file mode 100644 index 000000000..14a1de8fc --- /dev/null +++ b/docs/reference/supported-technologies.md @@ -0,0 +1,117 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/supported-technologies.html +--- + +# Supported technologies [supported-technologies] + +If your favorite technology is not supported yet, you can vote for it by participating in our [survey](https://docs.google.com/forms/d/18SgsVo9asGNFMjRqwdrk3wTHNwPhtHv4jE35hZRCL6A/). We will use the results to add support for the most requested technologies. + +Another option is to add a dependency to the agent’s [public API](/reference/public-api.md) in order to programmatically create custom transactions and spans. + +If you want to extend the auto-instrumentation capabilities of the agent, the [contributing guide](https://github.com/elastic/apm-agent-dotnet/blob/main/CONTRIBUTING.md) should get you started. + +::::{note} +If, for example, the HTTP client library of your choice is not listed, it means that there won’t be spans for those outgoing HTTP requests. If the web framework you are using is not supported, the agent will not capture transactions. +:::: + + + +## .NET versions [supported-dotnet-flavors] + +The agent works on every .NET flavor and version that supports .NET Standard 2.0. This means .NET Core 2.0 or newer, and .NET Framework 4.6.2* or newer. + +** Due to binding issues introduced by Microsoft, we recommend at least .NET Framework 4.7.2 for best compatibility.* + +::::{important} +While this library **should** work on .NET Core 2.0+, we limit our support to only those versions currently supported by Microsoft - .NET 6.0 and newer. + +:::: + + + +## Web frameworks [supported-web-frameworks] + +Automatic instrumentation for a web framework means a transaction is automatically created for each incoming request and it is named after the registered route. + +Automatic instrumentation is supported for the following web frameworks + +| Framework | Supported versions | Integration | +| --- | --- | --- | +| ASP.NET Core [1.0] | 2.1+ | [NuGet package](/reference/setup-asp-net-core.md) | +| ASP.NET (.NET Framework) in IIS [1.1] | 4.6.2+ (IIS 7.0 or newer) | [Profiler auto instrumentation](/reference/setup-auto-instrumentation.md)
*or*
[NuGet package](/reference/setup-asp-dot-net.md) | + + +## RPC Frameworks [supported-rpc-frameworks] + +The agent supports gRPC on .NET Core both on the client and the server side. Every gRPC call is automatically captured by the agent. + +Streaming is not supported; for streaming use-cases, the agent does not create transactions and spans automatically. + +| Framework | Supported versions | Integration | +| --- | --- | --- | +| gRPC [1.7] | Grpc.Net.Client 2.23.2+ *(client side)* | [NuGet package](/reference/setup-grpc.md) | +| ASP.NET Core 2.1+ *(server side)* | [NuGet package](/reference/setup-asp-net-core.md) | + + +## Data access technologies [supported-data-access-technologies] + +Automatic instrumentation is supported for the following data access technologies + +| Data access technology | Supported versions | Integration | +| --- | --- | --- | +| Azure CosmosDB [1.11] | Microsoft.Azure.Cosmos 3.0.0+ | [NuGet package](/reference/setup-azure-cosmosdb.md) | +| Microsoft.Azure.DocumentDB.Core 2.4.1+ | +| Microsoft.Azure.DocumentDB 2.4.1+ | +| Entity Framework Core [1.0] | Microsoft.EntityFrameworkCore 2.x+ | [NuGet package](/reference/setup-ef-core.md) | +| Entity Framework 6 [1.2] | EntityFramework 6.2+ | [NuGet package](/reference/setup-ef6.md) | +| Elasticsearch [1.6] | Elasticsearch.Net 7.6.0+ | [NuGet package](/reference/setup-elasticsearch.md) | +| NEST 7.6.0+ | +| MySQL [1.12] | See profiler documentation | [Profiler auto instrumentation](/reference/setup-auto-instrumentation.md) | +| MongoDB [1.9] | MongoDB.Driver 2.19.0+ | [NuGet package](/reference/setup-mongo-db.md) | +| Oracle [1.12] | See profiler documentation | [Profiler auto instrumentation](/reference/setup-auto-instrumentation.md) | +| PostgreSQL [1.12] | See profiler documentation | [Profiler auto instrumentation](/reference/setup-auto-instrumentation.md) | +| Redis [1.8] | StackExchange.Redis 2.0.495+ | [NuGet package](/reference/setup-stackexchange-redis.md) | +| SqlClient | System.Data.SqlClient 2.0.495+ [1.8] | [NuGet package](/reference/setup-sqlclient.md) | +| See profiler documentation [1.12] | [Profiler auto instrumentation](/reference/setup-auto-instrumentation.md) | +| SQLite [1.12] | See profiler documentation | [Profiler auto instrumentation](/reference/setup-auto-instrumentation.md) | + + +## Messaging systems [supported-messaging-systems] + +We support automatic instrumentation for the following messaging systems + +| Messaging system | Supported versions | Integration | +| --- | --- | --- | +| Azure Service Bus [1.10] | Microsoft.Azure.ServiceBus 3.0.0+ | [NuGet package](/reference/setup-azure-servicebus.md) | +| Azure.Messaging.ServiceBus 7.0.0+ | +| Azure Queue Storage [1.10] | Azure.Storage.Queues 12.6.0+ | [NuGet package](/reference/setup-azure-storage.md) | +| Kafka [1.12] | See profiler documentation | [Profiler auto instrumentation](/reference/setup-auto-instrumentation.md) | +| RabbitMQ [1.12] | See profiler documentation | [Profiler auto instrumentation](/reference/setup-auto-instrumentation.md) | + + +## Networking client-side technologies [supported-networking-client-side-technologies] + +Automatic instrumentation for networking client-side technology means an HTTP span is automatically created for each outgoing HTTP request and tracing headers are propagated. + +| Framework | Supported versions | Integration | +| --- | --- | --- | +| System.Net.Http.HttpClient [1.0] | *built-in* | [part of Elastic.Apm](/reference/public-api.md#setup-http) | +| System.Net.HttpWebRequest [1.1] | + + +## Cloud services [supported-cloud-services] + +Automatic instrumentation for the following cloud services + +| Cloud service | Supported versions | Integration | +| --- | --- | --- | +| Azure CosmosDB [1.11] | Microsoft.Azure.Cosmos 3.0.0+ | [NuGet package](/reference/setup-azure-cosmosdb.md) | +| Microsoft.Azure.DocumentDB.Core 2.4.1+ | +| Microsoft.Azure.DocumentDB 2.4.1+ | +| Azure Service Bus [1.10] | Microsoft.Azure.ServiceBus 3.0.0+ | [NuGet package](/reference/setup-azure-servicebus.md) | +| Azure.Messaging.ServiceBus 7.0.0+ | +| Azure Storage [1.10] | Azure.Storage.Blobs 12.8.0+ | [NuGet package](/reference/setup-azure-storage.md) | +| Azure.Storage.Queues 12.6.0+ | +| Azure.Storage.Files.Shares 12.6.0+ | + diff --git a/docs/reference/toc.yml b/docs/reference/toc.yml new file mode 100644 index 000000000..04721be63 --- /dev/null +++ b/docs/reference/toc.yml @@ -0,0 +1,46 @@ +project: 'APM .NET agent reference' +toc: + - file: index.md + - file: set-up-apm-net-agent.md + children: + - file: setup-auto-instrumentation.md + - file: setup-asp-net-core.md + - file: setup-dotnet-net-core.md + - file: setup-asp-dot-net.md + - file: setup-azure-functions.md + - file: setup-general.md + - file: nuget-packages.md + children: + - file: setup-ef-core.md + - file: setup-ef6.md + - file: setup-elasticsearch.md + - file: setup-grpc.md + - file: setup-sqlclient.md + - file: setup-stackexchange-redis.md + - file: setup-azure-cosmosdb.md + - file: setup-azure-servicebus.md + - file: setup-azure-storage.md + - file: setup-mongo-db.md + - file: supported-technologies.md + - file: configuration.md + children: + - file: configuration-on-asp-net-core.md + - file: configuration-for-windows-services.md + - file: configuration-on-asp-net.md + - file: config-core.md + - file: config-reporter.md + - file: config-http.md + - file: config-messaging.md + - file: config-stacktrace.md + - file: config-supportability.md + - file: config-all-options-summary.md + - file: public-api.md + - file: opentelemetry-bridge.md + - file: metrics.md + - file: logs.md + children: + - file: serilog.md + - file: nlog.md + - file: log-correlation-manual.md + - file: performance-tuning.md + - file: upgrading.md \ No newline at end of file diff --git a/docs/reference/upgrading.md b/docs/reference/upgrading.md new file mode 100644 index 000000000..1a4eb4eb6 --- /dev/null +++ b/docs/reference/upgrading.md @@ -0,0 +1,19 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/upgrading.html +--- + +# Upgrading [upgrading] + +Upgrades between minor versions of the agent, like from 1.1 to 1.2 are always backwards compatible. Upgrades that involve a major version bump often come with some backwards incompatible changes. + +Before upgrading the agent, be sure to review the: + +* [Agent release notes](/release-notes/index.md) +* [Agent and Server compatibility chart](docs-content://solutions/observability/apps/apm-agent-compatibility.md) + + +## End of life dates [end-of-life-dates] + +We love all our products, but sometimes we must say goodbye to a release so that we can continue moving forward on future development and innovation. Our [End of life policy](https://www.elastic.co/support/eol) defines how long a given release is considered supported, as well as how long a release is considered still in active development or maintenance. + diff --git a/docs/release-notes/breaking-changes.md b/docs/release-notes/breaking-changes.md new file mode 100644 index 000000000..37e663c30 --- /dev/null +++ b/docs/release-notes/breaking-changes.md @@ -0,0 +1,95 @@ +--- +navigation_title: "Elastic APM .NET Agent" +--- + +# Elastic APM .NET Agent breaking changes [elastic-apm-net-agent-breaking-changes] +Before you upgrade, carefully review the Elastic APM .NET Agent breaking changes and take the necessary steps to mitigate any issues. + +To learn how to upgrade, check out [Upgrading](/reference/upgrading.md). + +% ## Next version [elastic-apm-net-agent-nextversion-breaking-changes] +% **Release date:** Month day, year + +% ::::{dropdown} Title of breaking change +% Description of the breaking change. +% For more information, check [PR #](PR link). +% **Impact**
Impact of the breaking change. +% **Action**
Steps for mitigating deprecation impact. +% :::: + +## 1.13.0 [elastic-apm-net-agent-1130-breaking-changes] +**Release date:** December 2, 2024 + +We no longer ship net6.0 targets as .NET 6 is now out of support. Applications targetting net6.0 will continue to work, but fall down to the netstandard2.0 target which may not be as optimised. We therefore recommend updating your application to net8.0 or net9.0 prior to installing 1.31.0 of the Elastic.Apm.* packages. + +For more information, check [#2498](https://github.com/elastic/apm-agent-dotnet/pull/2498). + +## 1.29.0 [elastic-apm-net-agent-1290-breaking-changes] +**Release date:** September 18, 2024 + +This release includes a breaking change in how we parse and send transaction cookies. In 1.26.0, we introduced improved cookie redaction based on the SanitizeFieldNames configuration. To implement this, we extracted each cookie from the Cookie header, storing them in a cookie dictionary on the transaction request data. We have identified a problem with the storage of cookies that include period characters due to the mapping of such data when stored in the APM data stream. This behaviour can lead to lost transactions on requests which include such cookies. This is common in ASP.NET Core due to the default cookie names used for sessions, authentication, etc. + +In this release, we no longer parse out individual cookies, and the cookie Dictionary has been removed from the data model. This means that cookies will no longer be indexed individually. However, we have ensured that we retain the primary reason for the earlier change, which was to redact the values of sensitive cookies. Any cookies with a name matching the SanitizeFieldNames patterns will be redacted in the value of the Cookie header we store. + +For most consumers, we expect the impact to be minimal. However, if you were relying on the parsed cookie fields, adjustments will be necessary to work with the Cookie header value instead. + +No longer parse request cookies, but ensure they are still redacted in the Cookie header string. + +For more information, check [#2444](https://github.com/elastic/apm-agent-dotnet/pull/2444). + +## 1.21.0 [elastic-apm-net-agent-1210-breaking-changes] +**Release date:** April 5, 2023 + +This release includes two breaking changes that have minimal impact. + +We removed support for target frameworks which have gone into end-of-life support by Microsoft. The impact should be minimal, however as we continue to support netstandard2.0 and netstandard2.1 where applicable. +We removed the collection of GC metrics over ETW on .NET Full Framework. The collection over ETW requires elevated privileges, especially in IIS deployments. This runs counter to best practices. Since these are currently not displayed in the APM UI, while technically breaking, the impact should be minimal. The GC metric collection on modern .NET platforms is not impacted. + +* Remove ETW powered GC metrics on FullFramework. For more information, check [#2036](https://github.com/elastic/apm-agent-dotnet/pull/2036). +* Remove unsupported TFM’s. For more information, check [#2027](https://github.com/elastic/apm-agent-dotnet/pull/2027). + +## 1.14.0 [elastic-apm-net-agent-1140-breaking-changes] +**Release date:** February 9, 2022 + +Change unknown service.name to align with other agents. In the very rare cases when the agent is not able to autoamtically detect the name of a service, or it’s not manually set, it’ll use the default service name unknown-dotnet-service. In prior versions this was just unknown. + +For more information, check [#1586](https://github.com/elastic/apm-agent-dotnet/pull/1586) and [#1585](https://github.com/elastic/apm-agent-dotnet/issues/1585). + +## 1.12.0 [elastic-apm-net-agent-1120-breaking-changes] + +Auto-infer destination.service.resource and adapt public API. + +`boolean isExitSpan` parameter introduced to Start* and Capture* public APIs to denote when a span is an exit span. + +For more information, check [#1520](https://github.com/elastic/apm-agent-dotnet/pull/1520) and [#1330](https://github.com/elastic/apm-agent-dotnet/issues/1330). + +## 1.10.0 [elastic-apm-net-agent-1100-breaking-changes] + +Do not capture HTTP child spans for Elasticsearch. + +For more information, check [#1306](https://github.com/elastic/apm-agent-dotnet/pull/1306) and [#1276](https://github.com/elastic/apm-agent-dotnet/pull/1276). + +## 1.9.0 [elastic-apm-net-agent-190-breaking-changes] + +The agent tries to never throw any exception. Specifically instead of throwing InstanceAlreadyCreatedException, it will print an error log. + +For more information, check [#1161](https://github.com/elastic/apm-agent-dotnet/pull/1161) and [#1162](https://github.com/elastic/apm-agent-dotnet/pull/1162). + +## 1.7.0 [elastic-apm-net-agent-170-breaking-changes] + +Binary compatibility on `IExecutionSegment.CaptureException` and `IExecutionSegment.CaptureError` with libraries depending on previous version. If this happens you need to update Elastic.Apm to 1.7.0 in your projects. + +For more information, check [#1067](https://github.com/elastic/apm-agent-dotnet/issues/1067). + +## 1.4.0 [elastic-apm-net-agent-140-breaking-changes] + +We have some changes that are technically breaking changes. We made some helper classes internal that were never meant to be public. These are: `Elastic.Apm.Helpers.AgentTimeInstant`, `Elastic.Apm.Helpers.ContractExtensions`, `Elastic.Apm.Helpers.ObjectExtensions`, `Elastic.Apm.Helpers.ToStringBuilder`. None of these classes were documented or mentioned as part of the Public Agent API. We expect no usage of these classes outside the agent. + +## 1.0.0 [elastic-apm-net-agent-100-breaking-changes] + +We have some breaking changes in this release. We wanted to do these changes prior to our GA release and with this we hopefully avoid breaking changes in the upcoming versions. + +* For better naming we replaced the Elastic.Apm.All packages with Elastic.Apm.NetCoreAll. For more information, check [#371](https://github.com/elastic/apm-agent-dotnet/pull/371). +* Based on feedback we also renamed the UseElasticApm() method in the Elastic.Apm.NetCoreAll package to UseAllElasticApm - this method turns on every component of the Agent for ASP.NET Core. For more information, check [#371](https://github.com/elastic/apm-agent-dotnet/pull/371). +* Our logger abstraction, specifically the IApmLogger interface changed. For more information, check [#389](https://github.com/elastic/apm-agent-dotnet/pull/389). +* To follow the [Elastic Common Schema (ECS)][Elastic Common Schema (ECS)](ecs://docs/reference/index.md)), we renamed our Tags properties to Labels. For more information, check [#416](https://github.com/elastic/apm-agent-dotnet/pull/416). \ No newline at end of file diff --git a/docs/release-notes/index.md b/docs/release-notes/index.md new file mode 100644 index 000000000..abd32ff31 --- /dev/null +++ b/docs/release-notes/index.md @@ -0,0 +1,640 @@ +--- +navigation_title: "Elastic APM .NET Agent" +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/release-notes-1.x.html + - https://www.elastic.co/guide/en/apm/agent/dotnet/current/release-notes.html +--- + +# Elastic APM .NET Agent release notes [elastic-apm-net-agent-release-notes] + +Review the changes, fixes, and more in each version of Elastic APM .NET Agent. + +To check for security updates, go to [Security announcements for the Elastic stack](https://discuss.elastic.co/c/announcements/security-announcements/31). + +% Release notes includes only features, enhancements, and fixes. Add breaking changes, deprecations, and known issues to the applicable release notes sections. + +% version.next [elastic-apm-net-agent-versionext-release-notes] +% **Release date:** Month day, year + +% ### Features and enhancements [elastic-apm-net-agent-versionext-features-enhancements] + +% ### Fixes [elastic-apm-net-agent-versionext-fixes] + +## 1.31.0 [elastic-apm-net-agent-1310-release-notes] +**Release date:** December 2, 2024 + +### Features and enhancements [elastic-apm-net-agent-1310-features-enhancements] +* Phase one logger optimisations [#2503](https://github.com/elastic/apm-agent-dotnet/pull/2503) + +### Fixes [elastic-apm-net-agent-1310-fixes] +* Fixes and enhancements for Azure Functions [#2505](https://github.com/elastic/apm-agent-dotnet/pull/2505) +* Azure Function service name logic [#2508](https://github.com/elastic/apm-agent-dotnet/pull/2508) + +## 1.31.1 [elastic-apm-net-agent-1311-release-notes] +**Release date:** November 18, 2024 + +### Fixes [elastic-apm-net-agent-1311-fixes] +* Remove netcoreapp2.0 from Elastic.Apm.Profiler.Managed.Loader [#2471](https://github.com/elastic/apm-agent-dotnet/pull/2471) +* Fix span linking for Azure ServiceBus [#2474](https://github.com/elastic/apm-agent-dotnet/pull/2474) +* Support K8S_ATTACH environment variable for activation [#2482](https://github.com/elastic/apm-agent-dotnet/pull/2482) + +## 1.31.0 [elastic-apm-net-agent-1310-release-notes] +**Release date:** October 11, 2024 + +### Fixes [elastic-apm-net-agent-1310-fixes] +* Improve OTel bridge compatibility with existing Azure instrumentation [#2455](https://github.com/elastic/apm-agent-dotnet/pull/2455) +* Revert skipping of System.Web to fix profiler-based installation [#2457](https://github.com/elastic/apm-agent-dotnet/pull/2457) +* Limit attribute count and truncate values in ElasticActivityListener [#2461](https://github.com/elastic/apm-agent-dotnet/pull/2461) +* Add IntakeResponse deserialization for detailed error logging [#2460](https://github.com/elastic/apm-agent-dotnet/pull/2460) + +## 1.28.6 [elastic-apm-net-agent-1286-release-notes] +**Release date:** September 11, 2024 + +### Fixes [elastic-apm-net-agent-1286-fixes] +* Hard exclude several system processes from being auto instrumented [#2431](https://github.com/elastic/apm-agent-dotnet/pull/2431) +* Disabling the agent should not try to enqueue events, now a NOOP [#2436](https://github.com/elastic/apm-agent-dotnet/pull/2436) + +## 1.28.5 [elastic-apm-net-agent-1285-release-notes] +**Release date:** August 28, 2024 + +### Fixes [elastic-apm-net-agent-1285-fixes] +* Relax ECS container ID regex [#2430](https://github.com/elastic/apm-agent-dotnet/pull/2430) + +## 1.28.4 [elastic-apm-net-agent-1285-release-notes] +**Release date:** August 19, 2024 + +### Fixes [elastic-apm-net-agent-1284-fixes] +* Ensure we capture baggage when capturing Errors during unsampled transactions [#2427](https://github.com/elastic/apm-agent-dotnet/pull/2427) +* Ensure safer access to System.Web.Security.Roles [#2425](https://github.com/elastic/apm-agent-dotnet/pull/2425) +* Fix a bug that prevented the addition of filters to payloadsenders [#2426](https://github.com/elastic/apm-agent-dotnet/pull/2426) +* SetAgentActivationMethod throws CultureNotFoundException in global-invariant mode [#2423](https://github.com/elastic/apm-agent-dotnet/pull/2423) + +## 1.28.3 [elastic-apm-net-agent-1285-release-notes] +**Release date:** August 15, 2024 + +### Fixes [elastic-apm-net-agent-1283-fixes] +* Update to latest `MongoDB.Driver.Core` to address a breaking change [#2419](https://github.com/elastic/apm-agent-dotnet/pull/2419) +* Adding filters should not force initialization of Agent [#2418](https://github.com/elastic/apm-agent-dotnet/pull/2418) + +## 1.28.2 [elastic-apm-net-agent-1282-release-notes] +**Release date:** August 14, 2024 + +### Fixes [elastic-apm-net-agent-1282-fixes] +* Fixed check for SqlRoleProvider under AspNet Identity 2 [#2415](https://github.com/elastic/apm-agent-dotnet/pull/2415) + +## 1.28.1 [elastic-apm-net-agent-1281-release-notes] +**Release date:** August 12, 2024 + +### Features and enhancements [elastic-apm-net-agent-1281-features-enhancements] +* Global file logging, making it easier to diagnose the agent no matter the deployment type [#2371](https://github.com/elastic/apm-agent-dotnet/pull/2371) + +### Fixes [elastic-apm-net-agent-1281-fixes] +* Skip instrumentation of System.Web to prevent rare double configuration initialization issue [#2389](https://github.com/elastic/apm-agent-dotnet/pull/2411) + +## 1.28.0 [elastic-apm-net-agent-1289-release-notes] +**Release date:** July 3, 2024 + +### Fixes [elastic-apm-net-agent-1280-fixes] +* Fix Linux build dependency of glibc [#2389](https://github.com/elastic/apm-agent-dotnet/pull/2389) + +## 1.27.3 [elastic-apm-net-agent-1273-release-notes] +**Release date:** June 18, 2024 + +### Fixes [elastic-apm-net-agent-1273-fixes] +* Release Automation fix [#2380](https://github.com/elastic/apm-agent-dotnet/pull/2380) + +## 1.27.2 [elastic-apm-net-agent-1272-release-notes] +**Release date:** June 18, 2024 + +### Fixes [elastic-apm-net-agent-1272-fixes] +* Clean up dependency graph for .NET core installations [#2308](https://github.com/elastic/apm-agent-dotnet/pull/2308) +* Open Telemetry Bridge should only log when enabled [#2356](https://github.com/elastic/apm-agent-dotnet/pull/2356) +* Bump Microsoft.AspNetCore.Http dep to 2.1.22 [#2166](https://github.com/elastic/apm-agent-dotnet/pull/2166) +* Fix message format for logging in managed profiler [#2350](https://github.com/elastic/apm-agent-dotnet/pull/2350) +* Only mark bodies as redacted if explicitly configured to do so [#2225](https://github.com/elastic/apm-agent-dotnet/pull/2225) +* Do not read claims from SqlRoleProvider under classic ASP.NET [#2377](https://github.com/elastic/apm-agent-dotnet/pull/2377) + +## 1.27.1 [elastic-apm-net-agent-1271-release-notes] +**Release date:** May 16, 2024 + +### Fixes [elastic-apm-net-agent-1271-fixes] +* Remove invalid profiler method integrations [#2349](https://github.com/elastic/apm-agent-dotnet/pull/2349) + +## 1.27.0 [elastic-apm-net-agent-1270-release-notes] +**Release date:** April 30, 2024 + +### Features and enhancements [elastic-apm-net-agent-1270-features-enhancements] +* Add `IServiceCollection` extension methods to register ApmAgent [#2331](https://github.com/elastic/apm-agent-dotnet/pull/2331) +* Add support for `transaction_name_groups` and `use_path_as_transaction_name` [#2326](https://github.com/elastic/apm-agent-dotnet/pull/2326) + + +* Fix race condition on Add in redis profiler [#2303](https://github.com/elastic/apm-agent-dotnet/pull/2303) +* Further logging refinements in ElasticApmModule [#2299](https://github.com/elastic/apm-agent-dotnet/pull/2299) +* Update to .NET 8 SDK [#2304](https://github.com/elastic/apm-agent-dotnet/pull/2304) +* Update troubleshooting section of docs [#2302](https://github.com/elastic/apm-agent-dotnet/pull/2302) +* Fix bug when handling of multiple cookie entries with the same name [#2310](https://github.com/elastic/apm-agent-dotnet/pull/2310) +* Clarify logging behaviour in troubleshooting doc [#2314](https://github.com/elastic/apm-agent-dotnet/pull/2314) +* Fix agent-zip for 5.0.0 [#2336](https://github.com/elastic/apm-agent-dotnet/pull/2336) + +## 1.26.0 [elastic-apm-net-agent-1260-release-notes] +**Release date:** February 20, 2024 +This release introduces more thorough sanitization of request/response cookies to align with the APM spec. The incoming `Cookie` is now redacted by default. The cookies it contains are extracted and sanitized according to the `SanitizeFieldNames` configuration. Response headers are now correctly sanitized, including the `Set-Cookie` header. This is a behaviour change! + +### Features and enhancements [elastic-apm-net-agent-1260-features-enhancements] +* Fully implement the sanitization spec for request/response headers [#2290](https://github.com/elastic/apm-agent-dotnet/pull/2290) +* Include process information in metadata stanza when emitting events to apm-server [#2272](https://github.com/elastic/apm-agent-dotnet/pull/2272) +* Switch to Licence expression rather than file [#2264](https://github.com/elastic/apm-agent-dotnet/pull/2264) + +### Fixes [elastic-apm-net-agent-1271-fixes] +* Cleanup of packages thanks to Framework reference [#2267](https://github.com/elastic/apm-agent-dotnet/pull/2267) +* Limit memory usage when capturing SOAP request bodies [#2274](https://github.com/elastic/apm-agent-dotnet/pull/2274) +* Address a few synchronization issues in the codebase [#2276](https://github.com/elastic/apm-agent-dotnet/pull/2276) +* Truncate unknown keys logging from central config parser [#2277](https://github.com/elastic/apm-agent-dotnet/pull/2277) +* Ensure exposed default constants are readonly [#2278](https://github.com/elastic/apm-agent-dotnet/pull/2278) +* Fix duplicate key errors on dropped span stats update [#2283](https://github.com/elastic/apm-agent-dotnet/pull/2283) +* Remove RegexConverter, not used in serialization from and to apm-server [#2279](https://github.com/elastic/apm-agent-dotnet/pull/2279) +* Cleanup some dead code and one instance of null propagation in tooling NOT userfacing code +[#2280](https://github.com/elastic/apm-agent-dotnet/pull/2280) + +## 1.25.3 [elastic-apm-net-agent-1253-release-notes] +**Release date:** January 8, 2024 + +### Fixes [elastic-apm-net-agent-1253-fixes] +* TagObjects not guaranteed to be unique [#2241](https://github.com/elastic/apm-agent-dotnet/pull/2241) +* Move logging caching over to ConditionalWeaktable [#2242](https://github.com/elastic/apm-agent-dotnet/pull/2242) +* Add additional logging to outgoing http call propagation [#2247](https://github.com/elastic/apm-agent-dotnet/pull/2247) +* Address multiple structured logging violations [#2249](https://github.com/elastic/apm-agent-dotnet/pull/2249) +* Update MongoDB drivers to 2.19.0 [#2245](https://github.com/elastic/apm-agent-dotnet/pull/2245) + +## 1.25.2 [elastic-apm-net-agent-1252-release-notes] +**Release date:** December 13, 2023 +This release fixes a bug in `Elastic.Apm.AspNetCore` when using ` UseElasticApm()` not correctly setting status codes. The bug was not present in the more commonly used `Elastic.Apm.NetCoreAll` since it uses a `DiagnosticListener` approach. With this release we ensure both packages use the exact same `DiagnosticListener` mechanism to instrument ASP.NET Core. + +### Fixes [elastic-apm-net-agent-1252-fixes] +* Remove ApmMiddleWare, only use DiagnosticSource listener for ASP.NET Core [#2213](https://github.com/elastic/apm-agent-dotnet/pull/2213) +* Move StartupHooks over to netstandard2.0 [#2239](https://github.com/elastic/apm-agent-dotnet/pull/2239) + +## 1.25.1 [elastic-apm-net-agent-1251-release-notes] +**Release date:** November 21, 2023 + +### Fixes [elastic-apm-net-agent-1251-fixes] +* Prevent server certificate callback runtime exception [#2213](https://github.com/elastic/apm-agent-dotnet/pull/2213) +* Fix duration.sum.us value in JSON [#2219](https://github.com/elastic/apm-agent-dotnet/pull/2219) +* Return total memory when limit is max value [#2214](https://github.com/elastic/apm-agent-dotnet/pull/2214) +* Ensure baggage gets copied with baggage prefix by [#2220](https://github.com/elastic/apm-agent-dotnet/pull/2220) + +## 1.25.0 [elastic-apm-net-agent-1250-release-notes] +**Release date:** October 19, 2023 + +### Features and enhancements [elastic-apm-net-agent-1260-features-enhancements] +* Support OnExecuteRequestStep available in new .NET versions for IIS modules [#2196](https://github.com/elastic/apm-agent-dotnet/pull/2196) + +## 1.24.0 [elastic-apm-net-agent-1240-release-notes] +**Release date:** September 20, 2023 + +### Features and enhancements [elastic-apm-net-agent-1240-features-enhancements] +* Enable OpenTelemetryBridge by default [#2140](https://github.com/elastic/apm-agent-dotnet/pull/2140) +* Update and optimise OTel bridge [#2157](https://github.com/elastic/apm-agent-dotnet/pull/2157) +* Add Baggage support [#2147](https://github.com/elastic/apm-agent-dotnet/pull/2147) +* Trace in-process Azure Functions [#2160](https://github.com/elastic/apm-agent-dotnet/pull/2160) +* Internalize SqlClient Instrumentation [#2165](https://github.com/elastic/apm-agent-dotnet/pull/2165) + +### Fixes [elastic-apm-net-agent-1240-fixes] +* Ensure OpenTelemetryBridge respects Agents sampling decisions [#2170](https://github.com/elastic/apm-agent-dotnet/pull/2170) +* DroppedSpanStats: do not flatten duration [#2178](https://github.com/elastic/apm-agent-dotnet/pull/2178) +* Change *cloud.project.id* for GCP metadata to be the *project-id* [#2180](https://github.com/elastic/apm-agent-dotnet/pull/2180) +* Handle SqlExceptions when accessing user claims [#2182](https://github.com/elastic/apm-agent-dotnet/pull/2182) + +## 1.23.0 [elastic-apm-net-agent-1230-release-notes] +**Release date:** August 8, 2023 + +### Features and enhancements [elastic-apm-net-agent-1230-features-enhancements] +* .NET Full Framework now always loads configuration from web or app.config [#2069](https://github.com/elastic/apm-agent-dotnet/pull/2069) +* Add Npgsql 7.x support to profiler [#2103](https://github.com/elastic/apm-agent-dotnet/pull/2103) +* Backend dependencies granularity for NoSQL and Messaging [#2104](https://github.com/elastic/apm-agent-dotnet/pull/2104) +* Send domain name when detected [#2067](https://github.com/elastic/apm-agent-dotnet/pull/2067) +* Log when we detect LegacyAspNetSynchronizationContext [#2136](https://github.com/elastic/apm-agent-dotnet/pull/2136) + +### Fixes [elastic-apm-net-agent-1230-fixes] +* Fix to not send start stack trace when below configured duration [#2126](https://github.com/elastic/apm-agent-dotnet/pull/2126) +* Agent.Configuration now always points to ConfigurationStore’s configuration [#2109](https://github.com/elastic/apm-agent-dotnet/pull/2109) +* Reduce logging noise for stack frame capturing [#2142](https://github.com/elastic/apm-agent-dotnet/pull/2142) +* Move Redis Profiler registration to ConditionalWeakTable [#2148](https://github.com/elastic/apm-agent-dotnet/pull/2148) + +## 1.22.0 [elastic-apm-net-agent-1220-release-notes] +**Release date:** April 28, 2023 + +### Features and enhancements [elastic-apm-net-agent-1230-features-enhancements] +* Enable listening to `Microsoft.Data.SqlClient.EventSource` on .NET full framework [#2050](https://github.com/elastic/apm-agent-dotnet/pull/2050) + +### Fixes [elastic-apm-net-agent-1230-fixes] +* Eager load APM configuration [#2054](https://github.com/elastic/apm-agent-dotnet/pull/2054) +* Increase logging of profiler if expected rejit target is not found [#2049](https://github.com/elastic/apm-agent-dotnet/pull/2049) + +## 1.21.0 [elastic-apm-net-agent-1210-release-notes] +**Release date:** April 5, 2023 + +### Fixes [elastic-apm-net-agent-1210-fixes] +* Prevent sending activation_method in metadata for 8.7.0 [#2041](https://github.com/elastic/apm-agent-dotnet/pull/2041) + +## 1.20.0 [elastic-apm-net-agent-1200-release-notes] +**Release date:** February 27, 2023 + +### Features and enhancements [elastic-apm-net-agent-1200-features-enhancements] +* Support for Azure Functions through new `Elastic.Apm.Azure.Functions` nuget package [#1981](https://github.com/elastic/apm-agent-dotnet/pull/1981) +* Support new Elasticsearch Client: `Elastic.Clients.Elasticsearch` [#1935](https://github.com/elastic/apm-agent-dotnet/pull/1935) +* Suppport latest version of Microsoft.Data.SqlClient [#1988](https://github.com/elastic/apm-agent-dotnet/pull/1988) +* Support latest version OracleManagedDataAccess [#1988](https://github.com/elastic/apm-agent-dotnet/pull/1968) +* Loose MSVC redistributable as requirement for the profiler [#1983](https://github.com/elastic/apm-agent-dotnet/pull/1983) +* Add support for sending agent activation method to the server [#1983](https://github.com/elastic/apm-agent-dotnet/pull/1976) + +### Fixes [elastic-apm-net-agent-1200-fixes] +* NullReferenceException in span compression [#1999](https://github.com/elastic/apm-agent-dotnet/pull/1999) +* Improve profiler logging by always enabling agent logging too [#1970](https://github.com/elastic/apm-agent-dotnet/pull/1970) +* Normalize OpenTelemetry Bridge config section to `OpenTelemetryBridgeEnabled` [#1972](https://github.com/elastic/apm-agent-dotnet/pull/1972) +* Try to enable TLS 1.2 in all scenarios [#1926](https://github.com/elastic/apm-agent-dotnet/pull/1926) +* OTel bridge span’s destination service may contain null resource [#1964](https://github.com/elastic/apm-agent-dotnet/pull/1964) +* AppSettings ElasticApm:Enabled is not fully honored in ASP.NET Classic [#1961](https://github.com/elastic/apm-agent-dotnet/pull/1961) + +## 1.19.0 [elastic-apm-net-agent-1190-release-notes] +**Release date:** December 5, 2022 + +### Features and enhancements [elastic-apm-net-agent-1190-features-enhancements] +* Improve handling of multiple agent initialization [#1867](https://github.com/elastic/apm-agent-dotnet/pull/1867) +* Enable CloudMetadataProvider on Azure Functions [#1877](https://github.com/elastic/apm-agent-dotnet/pull/1877) +* CentralConfig: handle MaxAge header with less than 5 sec according to spec [#1831](https://github.com/elastic/apm-agent-dotnet/issues/1831) and [#1892](https://github.com/elastic/apm-agent-dotnet/pull/1892) +* Add basic agent logging preamble [#1897](https://github.com/elastic/apm-agent-dotnet/pull/1897) +* Publish docker image with agent [#1665](https://github.com/elastic/apm-agent-dotnet/issues/1665) and [#1907](https://github.com/elastic/apm-agent-dotnet/pull/1907) +* Add .NET 7 support [#1860](https://github.com/elastic/apm-agent-dotnet/issues/1860) and [#1917](https://github.com/elastic/apm-agent-dotnet/pull/1917) +* Improve SOAP action parsing [#1930](https://github.com/elastic/apm-agent-dotnet/pull/1930) + +### Fixes [elastic-apm-net-agent-1190-fixes] +* Fix transaction trace id not aligned when transaction is created from OTel bridge without parent [#1881](https://github.com/elastic/apm-agent-dotnet/issues/1881) and [#1882](https://github.com/elastic/apm-agent-dotnet/pull/1882) +* Avoid NRE during startup hook init [#1904](https://github.com/elastic/apm-agent-dotnet/issues/1904) and [#1905](https://github.com/elastic/apm-agent-dotnet/pull/1905) +* Avoid panic in file-logging setup [#1918](https://github.com/elastic/apm-agent-dotnet/issues/1918) and [#1927](https://github.com/elastic/apm-agent-dotnet/pull/1927) +* Use Span timing instead of cumulative SqlCommand statistics [#1869](https://github.com/elastic/apm-agent-dotnet/issues/1869) and [#1922](https://github.com/elastic/apm-agent-dotnet/pull/1922) +* Enable DOTNET_STARTUP_HOOKS for .NET 7 [#1900](https://github.com/elastic/apm-agent-dotnet/issues/1900) and [#1933](https://github.com/elastic/apm-agent-dotnet/pull/1933) + +## 1.18.0 [elastic-apm-net-agent-1180-release-notes] +**Release date:** October 13, 2022 + +### Features and enhancements [elastic-apm-net-agent-1180-features-enhancements] +* Profiler based agent is now GA +* Capture request body in ASP.NET Full Framework [#379](https://github.com/elastic/apm-agent-dotnet/issues/379) and [#1806](https://github.com/elastic/apm-agent-dotnet/pull/1806) +* `UseWindowsCredentials`: new configuration to force the agent to use the credentials of the authenticated Windows user when events are sent to the APM Server [#1825](https://github.com/elastic/apm-agent-dotnet/issues/1825) and [#1832](https://github.com/elastic/apm-agent-dotnet/pull/1832) + +### Fixes [elastic-apm-net-agent-1180-fixes] +* Fix incorrect transaction name in ASP.NET Web Api [#1637](https://github.com/elastic/apm-agent-dotnet/issues/1645) and [#1800](https://github.com/elastic/apm-agent-dotnet/pull/1800) +* Fix potential NullReferenceException in TraceContinuationStrategy implementation [#1802](https://github.com/elastic/apm-agent-dotnet/issues/1802) and [#1803](https://github.com/elastic/apm-agent-dotnet/pull/1803) and [#1804](https://github.com/elastic/apm-agent-dotnet/pull/1804) +* Fix container ID parsing in AWS ECS/Fargate environments [#1779](https://github.com/elastic/apm-agent-dotnet/issues/1779) and [#1780](https://github.com/elastic/apm-agent-dotnet/pull/1780) +* Use correct default value for ExitSpanMinDuration [#1789](https://github.com/elastic/apm-agent-dotnet/issues/1789) and [#1814](https://github.com/elastic/apm-agent-dotnet/pull/1814) +* Fixed crashes on some SOAP 1.2 requests when using GetBufferedInputStream [#1759](https://github.com/elastic/apm-agent-dotnet/issues/1759) and [#1811](https://github.com/elastic/apm-agent-dotnet/pull/1811) +* Group MetricSets in BreakdownMetricsProvider [#1678](https://github.com/elastic/apm-agent-dotnet/issues/1678) and [#1816](https://github.com/elastic/apm-agent-dotnet/pull/1816) + +## 1.17.0 [elastic-apm-net-agent-1170-release-notes] +**Release date:** August 28, 2022 + +### Features and enhancements [elastic-apm-net-agent-1170-features-enhancements] +* Introduce the `TraceContinuationStrategy` config [#1637](https://github.com/elastic/apm-agent-dotnet/issues/1637) and [#1739](https://github.com/elastic/apm-agent-dotnet/pull/1739) +* Span Links with Azure ServiceBus [#1638](https://github.com/elastic/apm-agent-dotnet/issues/1638) and [#1749](https://github.com/elastic/apm-agent-dotnet/pull/1749) +* Improve db granularity [#1664](https://github.com/elastic/apm-agent-dotnet/issues/1664) and [#1765](https://github.com/elastic/apm-agent-dotnet/pull/1765) +* Add config option `span_stack_trace_min_duration` [#1529](https://github.com/elastic/apm-agent-dotnet/issues/1529) and [#1795](https://github.com/elastic/apm-agent-dotnet/pull/1795) + +### Fixes [elastic-apm-net-agent-1170-fixes] +* Fix default for the `ApplicationNamespaces` config [#1746](https://github.com/elastic/apm-agent-dotnet/pull/1746) +* Flow SynchronizationContext across public API calls [#1660](https://github.com/elastic/apm-agent-dotnet/issues/1660) and [#1755](https://github.com/elastic/apm-agent-dotnet/pull/1755) +* PayloadSender threading improvements [#1571](https://github.com/elastic/apm-agent-dotnet/issues/1571) and [#1753](https://github.com/elastic/apm-agent-dotnet/pull/1753) +* Include Accept header on APM server info call (caused errors when reading APM Server info) [#1624](https://github.com/elastic/apm-agent-dotnet/issues/1624) and [#1773](https://github.com/elastic/apm-agent-dotnet/pull/1773) +* Significantly improved the performance of database query parsing [#1763](https://github.com/elastic/apm-agent-dotnet/issues/1763) and [#1781](https://github.com/elastic/apm-agent-dotnet/pull/1781) +* Fix FillApmServerInfo : Invalid ElasticApm_ApiKey throws Exception [#1735](https://github.com/elastic/apm-agent-dotnet/issues/1735) and [#1787](https://github.com/elastic/apm-agent-dotnet/pull/1787) + +## 1.16.1 [elastic-apm-net-agent-1161-release-notes] +**Release date:** June 15, 2022 + +### Features and enhancements [elastic-apm-net-agent-1161-features-enhancements] +* Improved logging around fetching central configuration [#1626](https://github.com/elastic/apm-agent-dotnet/issues/1626) and [#1732](https://github.com/elastic/apm-agent-dotnet/pull/1732) + +### Fixes [elastic-apm-net-agent-1161-fixes] +* Crash during assembly loading with the profiler based agent [#1705](https://github.com/elastic/apm-agent-dotnet/issues/1705) and [#1710](https://github.com/elastic/apm-agent-dotnet/pull/1710) +* Handling RouteData with `null` in legacy ASP.NET Core 2.2 apps [#1729](https://github.com/elastic/apm-agent-dotnet/issues/1729) + +## 1.16.0 [elastic-apm-net-agent-1160-release-notes] +**Release date:** June 2, 2022 + +### Features and enhancements [elastic-apm-net-agent-1160-features-enhancements] +* Automatic capturing of incoming HTTP Requests on ASP.NET Core with the Profiler based agent [#1610](https://github.com/elastic/apm-agent-dotnet/issues/1610) and [#1726](https://github.com/elastic/apm-agent-dotnet/pull/1726) + +### Fixes [elastic-apm-net-agent-1160-fixes] +* By disabling `system.cpu.total.norm.pct`, the agent won’t create any instance of the `PerformanceCounter` type (workaround for issue: [#1724](https://github.com/elastic/apm-agent-dotnet/issues/1724) and [#1725](https://github.com/elastic/apm-agent-dotnet/pull/1725) +* Transaction names for incoming HTTP requests returning 404 but matching a valid route, will include the URL path instead of using `unknown route` [#1715](https://github.com/elastic/apm-agent-dotnet/issues/1715) and [#1723](https://github.com/elastic/apm-agent-dotnet/pull/1723) + +## 1.15.0 [elastic-apm-net-agent-1150-release-notes] +**Release date:** May 12, 2022 + +### Features and enhancements [elastic-apm-net-agent-1160-features-enhancements] +* Improved database span names based on parsed SQL statements [#242](https://github.com/elastic/apm-agent-dotnet/issues/242) and [#1657](https://github.com/elastic/apm-agent-dotnet/pull/1657) + +### Fixes [elastic-apm-net-agent-1150-fixes] +* Dedicated working loop thread for sending APM events [#1571](https://github.com/elastic/apm-agent-dotnet/issues/1571) and [#1670](https://github.com/elastic/apm-agent-dotnet/pull/1670) +* Fixed span type for MongoDB - with this a MongoDB logo will show up on the service map [#1677](https://github.com/elastic/apm-agent-dotnet/pull/1677) +* InvalidCastException in `AspNetCoreDiagnosticListener` [#1674](https://github.com/elastic/apm-agent-dotnet/pull/1674) +* MVC: handling `area:null` when creating transaction name based on routing [#1683](https://github.com/elastic/apm-agent-dotnet/pull/1683) +* Handle missing `.Stop` events in `AspNetCoreDiagnosticListener` [#1676](https://github.com/elastic/apm-agent-dotnet/issues/1676) and [#1685](https://github.com/elastic/apm-agent-dotnet/pull/1685) + +## 1.14.1 [elastic-apm-net-agent-1141-release-notes] +**Release date:** March 10, 2022 + +### Fixes [elastic-apm-net-agent-1150-fixes] +* Make sure events are sent after APM Server timeout [#1630](https://github.com/elastic/apm-agent-dotnet/pull/1630) and [#1634](https://github.com/elastic/apm-agent-dotnet/pull/1634) +* Error on composite span validation [#1631](https://github.com/elastic/apm-agent-dotnet/issues/1631) and [#1639](https://github.com/elastic/apm-agent-dotnet/pull/1639) +* OpenTelemetry (Activity) bridge - APM Server version check [#1648](https://github.com/elastic/apm-agent-dotnet/pull/1648) + +## 1.14.0 [elastic-apm-net-agent-1140-release-notes] +**Release date:** February 9, 2022 + +### Features and enhancements [elastic-apm-net-agent-1140-features-enhancements] +* Span compression and dropping fast exit spans. New settings: `ExitSpanMinDuration`, `SpanCompressionEnabled`, `SpanCompressionExactMatchMaxDuration`, `SpanCompressionSameKindMaxDuration` [#1329](https://github.com/elastic/apm-agent-dotnet/issues/1329) and [#1475](https://github.com/elastic/apm-agent-dotnet/issues/1475) and [#1620](https://github.com/elastic/apm-agent-dotnet/pull/1620) +* NpgSql 6.x support [#1602](https://github.com/elastic/apm-agent-dotnet/issues/1602) and [#1611](https://github.com/elastic/apm-agent-dotnet/pull/1611) +* Capture transaction name on errors [#1574](https://github.com/elastic/apm-agent-dotnet/issues/1574) and [#1589](https://github.com/elastic/apm-agent-dotnet/pull/1589) + +### Fixes [elastic-apm-net-agent-1140-fixes] +* .NET 6 support with startup hook [#1590](https://github.com/elastic/apm-agent-dotnet/issues/1590) and [#1603](https://github.com/elastic/apm-agent-dotnet/pull/1603) + +## 1.13.0 [elastic-apm-net-agent-1130-release-notes] +**Release date:** January 12, 2022 + +### Features and enhancements [elastic-apm-net-agent-1140-features-enhancements] +* OpenTelemetry Bridge - integration with `System.Diagnostics.Activity` - Beta [#1521](https://github.com/elastic/apm-agent-dotnet/issues/1521) and [#1498](https://github.com/elastic/apm-agent-dotnet/pull/1498) + +## 1.12.1 [elastic-apm-net-agent-1121-release-notes] + +### Fixes [elastic-apm-net-agent-1121-fixes] +* Failed sending event error with missing span.context.destination.service.name required field on older APM Servers [#1563](https://github.com/elastic/apm-agent-dotnet/issues/1563) and [#1564](https://github.com/elastic/apm-agent-dotnet/pull/1564) ) + +## 1.12.0 [elastic-apm-net-agent-1120-release-notes] + +### Features and enhancements [elastic-apm-net-agent-1120-features-enhancements] +* Implement Dropped span statistics [#1511](https://github.com/elastic/apm-agent-dotnet/pull/1511) +* Ignore duplicate Diagnostic listener subscriptions [#1119](https://github.com/elastic/apm-agent-dotnet/issues/1119) and [#1515](https://github.com/elastic/apm-agent-dotnet/pull/1515) +* Implement User-Agent spec for .NET agent [#1525](https://github.com/elastic/apm-agent-dotnet/pull/1525) and [#1518](https://github.com/elastic/apm-agent-dotnet/pull/1518) +* Add message related properties to transactions and spans [#1512](https://github.com/elastic/apm-agent-dotnet/issues/1512) +* Add profiler auto instrumentation [#1522](https://github.com/elastic/apm-agent-dotnet/issues/1522) and [#1534](https://github.com/elastic/apm-agent-dotnet/pull/1534) +* Add profiler auto instrumentation for RabbitMQ [#1223](https://github.com/elastic/apm-agent-dotnet/issues/1223) and [#1548](https://github.com/elastic/apm-agent-dotnet/pull/1548) +* Platform detection: Handle .NET 6 [#1513](https://github.com/elastic/apm-agent-dotnet/issues/1513) and [#1528](https://github.com/elastic/apm-agent-dotnet/pull/1528) +* Remove use of Socket.Encrypted to determine secure [#1492](https://github.com/elastic/apm-agent-dotnet/pull/1492) +* Auto-infer destination.service.resource and adapt public API [#1330](https://github.com/elastic/apm-agent-dotnet/issues/1330) and [#1520](https://github.com/elastic/apm-agent-dotnet/pull/1520) +* Stop recording transaction metrics [#1523](https://github.com/elastic/apm-agent-dotnet/issues/1523) and [#1540](https://github.com/elastic/apm-agent-dotnet/pull/1540) + +### Fixes [elastic-apm-net-agent-1120-fixes] +* Capture spans for new Azure Storage SDKs [#1352](https://github.com/elastic/apm-agent-dotnet/issues/1352) and [#1484](https://github.com/elastic/apm-agent-dotnet/pull/1484) +* Use Environment.MachineName to get HostName [#1504](https://github.com/elastic/apm-agent-dotnet/issues/1504) and [#1509](https://github.com/elastic/apm-agent-dotnet/pull/1509) +* Check context is not null when sanitizing error request headers [#1503](https://github.com/elastic/apm-agent-dotnet/issues/1503) and [#1510](https://github.com/elastic/apm-agent-dotnet/pull/1510) +* Improve Performance counter handling for metrics on Windows [#1505](https://github.com/elastic/apm-agent-dotnet/issues/1505) and [#1536](https://github.com/elastic/apm-agent-dotnet/pull/1536) +* Collect .NET Framework GC metrics only when filtering supported [#1346](https://github.com/elastic/apm-agent-dotnet/issues/1346) and [#1538](https://github.com/elastic/apm-agent-dotnet/pull/1538) +* Handle enabled/recording=false configuration when capturing errors [#1557](https://github.com/elastic/apm-agent-dotnet/pull/1557) + +## 1.11.1 [elastic-apm-net-agent-1111-release-notes] + +### Features and enhancements [elastic-apm-net-agent-1111-features-enhancements] +* Serialize to writer directly [#1354](https://github.com/elastic/apm-agent-dotnet/pull/1354) +* Better logging in PayloadSenderV2 on task cancellation [#1356](https://github.com/elastic/apm-agent-dotnet/pull/1356) +* Propagate Trace context in exit spans [#1350](https://github.com/elastic/apm-agent-dotnet/issues/1350), [#1344](https://github.com/elastic/apm-agent-dotnet/issues/1344), and [#1358](https://github.com/elastic/apm-agent-dotnet/pull/1358) +* Get Command and Key for StackExchange.Redis spans [#1364](https://github.com/elastic/apm-agent-dotnet/issues/1364) and [#1374](https://github.com/elastic/apm-agent-dotnet/pull/1374) +* Add CosmosDB integration to NetCoreAll [#1474](https://github.com/elastic/apm-agent-dotnet/pull/1474) +* Use 10K limit for CaptureBody similar to the Java agent [#1359](https://github.com/elastic/apm-agent-dotnet/issues/1359) and [#1368](https://github.com/elastic/apm-agent-dotnet/pull/1368) + +### Fixes [elastic-apm-net-agent-1111-fixes] +* Unset parentId if TraceContextIgnoreSampledFalse is active [#1362](https://github.com/elastic/apm-agent-dotnet/pull/1362) +* Make sure BreakdownMetricsProvider prints 1K warning only once per collection [#1361](https://github.com/elastic/apm-agent-dotnet/issues/1361) and [#1367](https://github.com/elastic/apm-agent-dotnet/pull/1367) +* Sanitize Central config request URI and headers in logs [#1376](https://github.com/elastic/apm-agent-dotnet/issues/1376) and [#1471](https://github.com/elastic/apm-agent-dotnet/pull/1471) +* Honor Transaction.Outcome set by public API in auto instrumentation [#1349](https://github.com/elastic/apm-agent-dotnet/issues/1349) and [#1472](https://github.com/elastic/apm-agent-dotnet/pull/1472) +* Use Kubernetes pod id determined from cgroup file [#1481](https://github.com/elastic/apm-agent-dotnet/pull/1481) + +## 1.11.0 [elastic-apm-net-agent-1110-release-notes] + +### Features and enhancements [elastic-apm-net-agent-1110-features-enhancements] +* CosmosDb support [#1154](https://github.com/elastic/apm-agent-dotnet/issues/1154) and [#1342](https://github.com/elastic/apm-agent-dotnet/pull/1342) +* Support "Time spent by span type" (aka Breakdown metrics) [#227](https://github.com/elastic/apm-agent-dotnet/issues/227) and [#1271](https://github.com/elastic/apm-agent-dotnet/pull/1271) +* Prefer W3C traceparent over elastic-apm-traceparent [#1302](https://github.com/elastic/apm-agent-dotnet/pull/1302) +* Add TraceContextIgnoreSampledFalse config setting [#1310](https://github.com/elastic/apm-agent-dotnet/pull/1310) +* Create transactions for Azure Service Bus Processors [#1321](https://github.com/elastic/apm-agent-dotnet/issues/1321) and [#1331](https://github.com/elastic/apm-agent-dotnet/pull/1331) + +## 1.10.0 [elastic-apm-net-agent-1100-release-notes] + +### Features and enhancements [elastic-apm-net-agent-1100-features-enhancements] +* Add instrumentation for Azure Service Bus [#1157](https://github.com/elastic/apm-agent-dotnet/issues/1157) and [#1225](https://github.com/elastic/apm-agent-dotnet/pull/1225) +* Add Azure storage integration [#1156](https://github.com/elastic/apm-agent-dotnet/issues/1156) and [#1155](https://github.com/elastic/apm-agent-dotnet/issues/1155) and [#1247](https://github.com/elastic/apm-agent-dotnet/pull/1247) +* Internalize `Newtonsoft.Json` - no more dependency on `Newtonsoft.Json` [#1241](https://github.com/elastic/apm-agent-dotnet/pull/1241) +* Internalize `Ben.Demystifier` - no more dependency on `Ben.Demystifier` [#1232](https://github.com/elastic/apm-agent-dotnet/issues/1232) and [#1275](https://github.com/elastic/apm-agent-dotnet/pull/1275) +* Add MongoDb support [#1158](https://github.com/elastic/apm-agent-dotnet/issues/1158) and [#1215](https://github.com/elastic/apm-agent-dotnet/pull/1215) +* Capture inner exceptions [#1267](https://github.com/elastic/apm-agent-dotnet/issues/1267) and [#1277](https://github.com/elastic/apm-agent-dotnet/pull/1277) +* Add configured hostname [#1289](https://github.com/elastic/apm-agent-dotnet/issues/1289) and [#1290](https://github.com/elastic/apm-agent-dotnet/pull/1290) +* Use TraceLogger as default logger in ASP.NET Full Framework [#1263](https://github.com/elastic/apm-agent-dotnet/issues/1263) and [#1288](https://github.com/elastic/apm-agent-dotnet/pull/1288) + +### Fixes [elastic-apm-net-agent-1100-fixes] +* Fix issue around setting `Recording` to `false` [#1250](https://github.com/elastic/apm-agent-dotnet/issues/1250) and [#1252](https://github.com/elastic/apm-agent-dotnet/pull/1252) +* ASP.NET: Move error capturing to Error event handler [#1259](https://github.com/elastic/apm-agent-dotnet/pull/1259) +* Use Logger to log exception in AgentComponents initialization [#1254](https://github.com/elastic/apm-agent-dotnet/issues/1254) and [#1305](https://github.com/elastic/apm-agent-dotnet/pull/1305) +* Fix `NullReferenceException` in Elastic.Apm.Extensions.Logging [#1309](https://github.com/elastic/apm-agent-dotnet/issues/1309) and [#1311](https://github.com/elastic/apm-agent-dotnet/pull/1311) + +## 1.9.0 [elastic-apm-net-agent-190-release-notes] + +### Features and enhancements [elastic-apm-net-agent-190-features-enhancements] +* Add GC time [#922](https://github.com/elastic/apm-agent-dotnet/issues/922) and [#925](https://github.com/elastic/apm-agent-dotnet/pull/925) +* Propagate sample rate through `tracestate` [#1021](https://github.com/elastic/apm-agent-dotnet/issues/1021) and [#1147](https://github.com/elastic/apm-agent-dotnet/pull/1147) + +### Fixes [elastic-apm-net-agent-190-fixes] +* Get transaction name from Web API controller route template [#1189](https://github.com/elastic/apm-agent-dotnet/pull/1189) + +## 1.8.1 [elastic-apm-net-agent-181-release-notes] + +### Features and enhancements [elastic-apm-net-agent-181-features-enhancements] +* Add GC Heap Stats capturing for .NET 5.0 [#1195](https://github.com/elastic/apm-agent-dotnet/issues/1195) and [#1196](https://github.com/elastic/apm-agent-dotnet/pull/1196) + +### Fixes [elastic-apm-net-agent-181-fixes] +* Lazily access the agent in ElasticApmProfiler redis integration [#1190](https://github.com/elastic/apm-agent-dotnet/issues/1190) and [#1192](https://github.com/elastic/apm-agent-dotnet/pull/1192) +* Add TargetFramework NET5.0 to Elastic.Apm.AspNetCore and related packages [#1194](https://github.com/elastic/apm-agent-dotnet/issues/1194) and [#1198](https://github.com/elastic/apm-agent-dotnet/pull/1198) + +## 1.8.0 [elastic-apm-net-agent-180-release-notes] + +### Features and enhancements [elastic-apm-net-agent-180-features-enhancements] +* Add support for capturing redis commands from StackExchange.Redis ([documentation](/reference/setup-stackexchange-redis.md)) [#874](https://github.com/elastic/apm-agent-dotnet/issues/874) and [#1063](https://github.com/elastic/apm-agent-dotnet/pull/1063) +* Introduce `ServerUrl` config - (`ServerUrls` is still working but will be removed in the future) [#1035](https://github.com/elastic/apm-agent-dotnet/issues/1035) and [#1065](https://github.com/elastic/apm-agent-dotnet/pull/1065) +* Support for more k8s cgroup path patterns [#968](https://github.com/elastic/apm-agent-dotnet/issues/968) and [#1048](https://github.com/elastic/apm-agent-dotnet/pull/1048) +* `SanitizeFieldNames` config became changeable though Kibana central configuration [#1082](https://github.com/elastic/apm-agent-dotnet/pull/1082) +* Azure App Service cloud metadata collection [#1083](https://github.com/elastic/apm-agent-dotnet/pull/1083) +* Capture error logs as APM errors from `Microsoft.Extensions.Logging` automatically and extend the Public API to capture custom logs as APM errors [#894](https://github.com/elastic/apm-agent-dotnet/issues/894) and [#1135](https://github.com/elastic/apm-agent-dotnet/pull/1135) +* Support changing log level through Kibana central configuration and support `"off"` level [#970](https://github.com/elastic/apm-agent-dotnet/issues/970) and [#1096](https://github.com/elastic/apm-agent-dotnet/pull/1096) + +### Fixes [elastic-apm-net-agent-180-fixes] +* `NullReferenceException` with disabled agent on `Transaction.Custom` [#1080](https://github.com/elastic/apm-agent-dotnet/issues/1080) and [#1081](https://github.com/elastic/apm-agent-dotnet/pull/1081) +* ASP.NET Core, enabled=false in `appsettings.json` does not disable public Agent API [#1077](https://github.com/elastic/apm-agent-dotnet/issues/1077) and [#1078](https://github.com/elastic/apm-agent-dotnet/pull/1078) +* `System.IO.IOException` on ASP.NET Classic [#1113](https://github.com/elastic/apm-agent-dotnet/issues/1113) and [#1115](https://github.com/elastic/apm-agent-dotnet/pull/1115) +* Memory issue with gRPC [#1116](https://github.com/elastic/apm-agent-dotnet/issues/1116) and [#1118](https://github.com/elastic/apm-agent-dotnet/pull/1118) +* Ensuring ETW sessions are terminated on agent shutdown [#897](https://github.com/elastic/apm-agent-dotnet/issues/897) and [#1124](https://github.com/elastic/apm-agent-dotnet/pull/1124) +* `NullReferenceException` with custom `IConfigurationReader` implementation in `MetricsCollector` [#1109](https://github.com/elastic/apm-agent-dotnet/pull/1109) +* Fixes around zero code change agent setup with `DOTNET_STARTUP_HOOKS` [#1138](https://github.com/elastic/apm-agent-dotnet/pull/1138) and [#1165](https://github.com/elastic/apm-agent-dotnet/pull/1165) +* Access `Request.InputStream` only when SOAP header present [#1113](https://github.com/elastic/apm-agent-dotnet/issues/1113) + and [#1115](https://github.com/elastic/apm-agent-dotnet/pull/1115) + +## 1.7.1 [elastic-apm-net-agent-171-release-notes] + +### Features and enhancements [elastic-apm-net-agent-180-features-enhancements] +* Introduce `GetLabel` method on `IExecutionSegment` [#1033](https://github.com/elastic/apm-agent-dotnet/issues/1033) and [#1057](https://github.com/elastic/apm-agent-dotnet/pull/1057) + +### Fixes [elastic-apm-net-agent-171-fixes] +* Increased transaction duration due to stack trace capturing [#1039](https://github.com/elastic/apm-agent-dotnet/issues/1039) and [#1052](https://github.com/elastic/apm-agent-dotnet/pull/1052) +* Warning with `Synchronous operations are disallowed` on ASP.NET Core during request body capturing [#1044](https://github.com/elastic/apm-agent-dotnet/issues/1044) and [#1053](https://github.com/elastic/apm-agent-dotnet/pull/1053) +* SqlClient instrumentation on .NET 5 [#1025](https://github.com/elastic/apm-agent-dotnet/issues/1025) and [#1042](https://github.com/elastic/apm-agent-dotnet/pull/1042) +* `UseAllElasticApm` with `IHostBuilder` missing auto instrumentation [#1059](https://github.com/elastic/apm-agent-dotnet/issues/1059) and [#1060](https://github.com/elastic/apm-agent-dotnet/pull/1060) + +## 1.7.0 [elastic-apm-net-agent-170-release-notes] + +### Features and enhancements [elastic-apm-net-agent-170-features-enhancements] +* Agent loading with zero code change on .NET Core [#71](https://github.com/elastic/apm-agent-dotnet/issues/71) and [#828](https://github.com/elastic/apm-agent-dotnet/pull/828) +* gRPC support [#478](https://github.com/elastic/apm-agent-dotnet/issues/478) and [#969](https://github.com/elastic/apm-agent-dotnet/pull/969) +* Add ability to configure Hostname [#932](https://github.com/elastic/apm-agent-dotnet/issues/932) and [#974](https://github.com/elastic/apm-agent-dotnet/pull/974) +* Add Enabled and Recording configuration #122) and [#997](https://github.com/elastic/apm-agent-dotnet/pull/997) +* Add `FullFrameworkConfigurationReaderType` config to load custom configuration reader on ASP.NET [#912](https://github.com/elastic/apm-agent-dotnet/pull/912) +* Capture User id and email on ASP.NET #540 and [#978](https://github.com/elastic/apm-agent-dotnet/pull/978) +* Support boolean and numeric labels in addition to string labels [#967](https://github.com/elastic/apm-agent-dotnet/issues/967), [#788](https://github.com/elastic/apm-agent-dotnet/issues/788), [#473](https://github.com/elastic/apm-agent-dotnet/issues/473), [#191](https://github.com/elastic/apm-agent-dotnet/issues/192), [#788](https://github.com/elastic/apm-agent-dotnet/issues/788), [#473](https://github.com/elastic/apm-agent-dotnet/issues/473), [#191](https://github.com/elastic/apm-agent-dotnet/issues/191), and [#982](https://github.com/elastic/apm-agent-dotnet/pull/982) +* Collecting metrics based on cGroup [#937](https://github.com/elastic/apm-agent-dotnet/issues/937) and [#1000](https://github.com/elastic/apm-agent-dotnet/pull/1000) +* `ITransaction.SetService` API to support multiple services in a single process [#1001](https://github.com/elastic/apm-agent-dotnet/issues/1001) and [#1002](https://github.com/elastic/apm-agent-dotnet/pull/1002) +* Collecting cloud metadata (supporting AWS, Azure, GCP) [#918](https://github.com/elastic/apm-agent-dotnet/issues/918) and [#1003](https://github.com/elastic/apm-agent-dotnet/pull/1003) +* Transaction grouping on ASP.NET [#201](https://github.com/elastic/apm-agent-dotnet/issues/) and [#973](https://github.com/elastic/apm-agent-dotnet/pull/973) +* Entity Framework 6 support on .NET Core [#902](https://github.com/elastic/apm-agent-dotnet/issues/902) and [#913](https://github.com/elastic/apm-agent-dotnet/pull/913) + +### Fixes [elastic-apm-net-agent-170-fixes] +* [#992](https://github.com/elastic/apm-agent-dotnet/pull/992) On ASP.NET Core `CurrentTransaction` is null in some cases (issues: [#934](https://github.com/elastic/apm-agent-dotnet/issues/934), [#972](https://github.com/elastic/apm-agent-dotnet/issues/972)) +* [#971](https://github.com/elastic/apm-agent-dotnet/pull/971) Avoid double initialization in `HostBuilderExtensions` +* [#999](https://github.com/elastic/apm-agent-dotnet/pull/999) Capture body with large file error (issue: [#960](https://github.com/elastic/apm-agent-dotnet/issues/960)) + +## 1.6.1 [elastic-apm-net-agent-161-release-notes] + +### Fixes [elastic-apm-net-agent-161-fixes] +* Service map: missing connection between .NET services ([#909](https://github.com/elastic/apm-agent-dotnet/pull/909)) + +## 1.6.0 [elastic-apm-net-agent-160-release-notes] + +### Features and enhancements [elastic-apm-net-agent-160-features-enhancements] +* Elasticsearch client instrumentation [#329](https://github.com/elastic/apm-agent-dotnet/pull/329) +* Introducing `Elastic.Apm.Extensions.Hosting` package with an extension method on `IHostBuilder` [#537](https://github.com/elastic/apm-agent-dotnet/pull/537) +* Stack trace improvements: async call stack demystification ([#847](https://github.com/elastic/apm-agent-dotnet/pull/847)) and showing frames from user code for outgoing HTTP calls ([#845](https://github.com/elastic/apm-agent-dotnet/pull/845)) +* Making fields on `IError` public [#847](https://github.com/elastic/apm-agent-dotnet/pull/847) +* Service map improvements: [#893](https://github.com/elastic/apm-agent-dotnet/pull/893) + +### Fixes [elastic-apm-net-agent-160-fixes] +* Missing traces from the Kibana traces list due to setting `Transaction.ParentId` to an `Activity` [#888](https://github.com/elastic/apm-agent-dotnet/pull/888) +* Exception around runtime detection [#859](https://github.com/elastic/apm-agent-dotnet/pull/859) +* Missing outgoing HTTP calls in .NET Framework applications and causing memory issues [#896](https://github.com/elastic/apm-agent-dotnet/pull/896) + +## 1.5.1 [elastic-apm-net-agent-151-release-notes] + +### Fixes [elastic-apm-net-agent-151-fixes] +* Memory issue in SqlEventListener [#851](https://github.com/elastic/apm-agent-dotnet/pull/851) + +## 1.5.0 [elastic-apm-net-agent-150-release-notes] + +### Features and enhancements [elastic-apm-net-agent-150-features-enhancements] +* Auto instrumentation for `SqlClient` ([documentation](/reference/setup-sqlclient.md)) +* Introducing Filter API [#792](https://github.com/elastic/apm-agent-dotnet/pull/792) ([documentation](/reference/public-api.md#filter-api)) +* Auto-detect culprit for exceptions [#740](https://github.com/elastic/apm-agent-dotnet/pull/740) +* New config settings: `ExcludedNamespaces`, `ApplicationNamespaces` ([documentation](/reference/config-all-options-summary.md)) +* Keep `Activity.Current.TraceId` in sync with the Trace ID used by the agent [#800](https://github.com/elastic/apm-agent-dotnet/pull/800) +* Report Kubernetes system metadata [#741](https://github.com/elastic/apm-agent-dotnet/pull/741) + +### Fixes [elastic-apm-net-agent-150-fixes] +* Database connection string parsing issue with Oracle [#795](https://github.com/elastic/apm-agent-dotnet/pull/795) + +## 1.4.0 [elastic-apm-net-agent-140-release-notes] + +### Features and enhancements [elastic-apm-net-agent-140-features-enhancements] +* Introducing `ITransaction.EnsureParentId()` to integrate with RUM in dynamically loaded HTML pages (including page loads in ASP.NET Core) [#771](https://github.com/elastic/apm-agent-dotnet/pull/771) +* New config setting: `ApiKey` [#733](https://github.com/elastic/apm-agent-dotnet/pull/733) + +### Fixes [elastic-apm-net-agent-140-fixes] +* Memory issue in .NET Full Framework with default metrics turned on [#750](https://github.com/elastic/apm-agent-dotnet/pull/750) +* Parsing for Oracle connection strings [#749](https://github.com/elastic/apm-agent-dotnet/pull/749) +* `StackOverflowException` when using the `Elastic.Apm.SerilogEnricher` package and the log level is set to `Verbose` [#753](https://github.com/elastic/apm-agent-dotnet/pull/753) + +## 1.3.1 [elastic-apm-net-agent-131-release-notes] + +### Fixes [elastic-apm-net-agent-131-fixes] +* Fix log spamming issues [#736](https://github.com/elastic/apm-agent-dotnet/pull/736), [#738](https://github.com/elastic/apm-agent-dotnet/pull/738) +* Fix turning HTTP 415 responses in ASP.NET Core to HTTP 500 when request body capturing is active [#739](https://github.com/elastic/apm-agent-dotnet/pull/739) +* Fix disabling GC metrics collection in case no GC is triggered during the first "5*MetricsInterval" of the process [#745](https://github.com/elastic/apm-agent-dotnet/pull/745) + +## 1.3.0 [elastic-apm-net-agent-130-release-notes] + +### Features and enhancements [elastic-apm-net-agent-130-features-enhancements] +* New GC metrics: `clr.gc.count`, `clr.gc.gen[X]size`, where [X]: heap generation [#697](https://github.com/elastic/apm-agent-dotnet/pull/697) +* Capturing SOAP action name as part of the transaction name [#683](https://github.com/elastic/apm-agent-dotnet/pull/683) +* New config options: `ServiceNodeName`, `VerifyServerCert`, `DisableMetrics`, `UseElasticTraceparentHeader` ([docs](/reference/config-all-options-summary.md)) +* Full [W3C TraceContext](https://www.w3.org/TR/trace-context) support [#717](https://github.com/elastic/apm-agent-dotnet/pull/717) + +### Fixes [elastic-apm-net-agent-130-fixes] +* Fix transaction name generation in ASP.NET Core 3.x [#647](https://github.com/elastic/apm-agent-dotnet/pull/647) +* Fix around HTTP request body sanitization [#712](https://github.com/elastic/apm-agent-dotnet/pull/712) + +## 1.2.0 [elastic-apm-net-agent-120-release-notes] + +### Features and enhancements [elastic-apm-net-agent-120-features-enhancements] +* Entity framework support with Interceptor ([docs](/reference/setup-ef6.md)) +* Sanitization of HTTP headers and request body ([docs](/reference/config-core.md#config-sanitize-field-names)) +* Central configuration - 2 new configs: `CAPTURE_BODY` and `TRANSACTION_MAX_SPANS`. [#577](https://github.com/elastic/apm-agent-dotnet/pull/577). +* Support for global labels ([docs](/reference/config-core.md#config-global-labels)) +* Custom context ([docs](/reference/public-api.md#api-transaction-context)) +* Dropping support for ASP.NET Core 2.0 (which is already end of life) ([docs](/reference/supported-technologies.md#supported-web-frameworks)) + +### Fixes [elastic-apm-net-agent-120-fixes] +* De-dotting labels. [#583](https://github.com/elastic/apm-agent-dotnet/pull/583). +* Request body capturing TypeLoadException in ASP.NET Core 3.0. [#604](https://github.com/elastic/apm-agent-dotnet/pull/604). +* Metrics collection: filtering NaN and Infinity. [#589](https://github.com/elastic/apm-agent-dotnet/pull/589). + +## 1.1.2 [elastic-apm-net-agent-112-release-notes] + +### Fixes [elastic-apm-net-agent-112-fixes] +* Capturing request body with ASP.NET Core erased the body in some scenarios [#539](https://github.com/elastic/apm-agent-dotnet/pull/539). +* Integration with Serilog caused missing logs and diagnostic traces with `NullReferenceException` [#544](https://github.com/elastic/apm-agent-dotnet/pull/544), [#545](https://github.com/elastic/apm-agent-dotnet/pull/545). + +## 1.1.1 [elastic-apm-net-agent-111-release-notes] + +### Features and enhancements [elastic-apm-net-agent-120-features-enhancements] +* Configure transaction max spans. [#472](https://github.com/elastic/apm-agent-dotnet/pull/472) + +### Fixes [elastic-apm-net-agent-111-fixes] +* Fixing missing "Date Modified" field on the files from the `1.1.0` packages causing an error while executing `dotnet pack` or `nuget pack` on a project with Elastic APM Agent packages. [#527](https://github.com/elastic/apm-agent-dotnet/pull/527) + +## 1.1.0 [elastic-apm-net-agent-110-release-notes] + +### Features and enhancements [elastic-apm-net-agent-110-features-enhancements] +* ASP.NET Support, documentation can be found [here](/reference/setup-asp-dot-net.md) +* Central configuration (Beta) + +### Fixes [elastic-apm-net-agent-110-fixes] +* Addressed some performance issues [#359](https://github.com/elastic/apm-agent-dotnet/pull/359) +* Improved error handling in ASP.NET Core [#512](https://github.com/elastic/apm-agent-dotnet/pull/512) +* Fix for mono [#164](https://github.com/elastic/apm-agent-dotnet/pull/164) + +## 1.0.1 [elastic-apm-net-agent-101-release-notes] + +### Features and enhancements [elastic-apm-net-agent-101-features-enhancements] +* Reading request body in ASP.NET Core. Also introduced two new settings: `CaptureBody` and `CaptureBodyContentTypes`. By default this feature is turned off, this is an opt-in feature and can be turned on with the `CaptureBody` setting. [#402](https://github.com/elastic/apm-agent-dotnet/pull/402) + +### Fixes [elastic-apm-net-agent-101-fixes] +* `NullReferenceException` on .NET Framework with outgoing HTTP calls created with `HttpClient` in case the response code is HTTP3xx [#450](https://github.com/elastic/apm-agent-dotnet/pull/450) +* Added missing `net461` target to the [`Elastic.Apm`](https://www.nuget.org/packages/Elastic.Apm/) package +* Handling [`Labels`](/reference/public-api.md#api-transaction-tags) with `null` [#429](https://github.com/elastic/apm-agent-dotnet/pull/429) + +## 1.0.0 [elastic-apm-net-agent-100-release-notes] +The 1.0.0 GA release of the Elastic APM .NET Agent. Stabilization of the 1.0.0-beta feature for production usage. + +### Features and enhancements [elastic-apm-net-agent-100-features-enhancements] +* Out of the box integration with `ILoggerFactory` and the logging infrastructure in ASP.NET Core [#249](https://github.com/elastic/apm-agent-dotnet/pull/249) +* Introduced `StackTraceLimit` and `SpanFramesMinDurationInMilliseconds` configs [#374](https://github.com/elastic/apm-agent-dotnet/pull/374) +* The Public Agent API now support `Elastic.Apm.Agent.Tracer.CurrentSpan` [#391](https://github.com/elastic/apm-agent-dotnet/pull/391) + +### Fixes [elastic-apm-net-agent-100-fixes] +* Thread safety for some bookkeeping around spans [#394](https://github.com/elastic/apm-agent-dotnet/pull/394) +* Auto instrumentation automatically creates sub-spans in case a span is already active [#391](https://github.com/elastic/apm-agent-dotnet/pull/391) + diff --git a/docs/release-notes/known-issues.md b/docs/release-notes/known-issues.md new file mode 100644 index 000000000..454f3fb39 --- /dev/null +++ b/docs/release-notes/known-issues.md @@ -0,0 +1,19 @@ +--- +navigation_title: "Elastic APM .NET Agent" +--- + +# Elastic APM .NET Agent known issues [elastic-apm-net-agent-known-issues] + +% Use the following template to add entries to this page. + +% :::{dropdown} Title of known issue +% **Details** +% On [Month/Day/Year], a known issue was discovered that [description of known issue]. + +% **Workaround** +% Workaround description. + +% **Resolved** +% On [Month/Day/Year], this issue was resolved. + +::: diff --git a/docs/release-notes/toc.yml b/docs/release-notes/toc.yml new file mode 100644 index 000000000..7000d42b9 --- /dev/null +++ b/docs/release-notes/toc.yml @@ -0,0 +1,4 @@ +toc: + - file: index.md + - file: known-issues.md + - file: breaking-changes.md \ No newline at end of file